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Preface 


This manual describes how to program Xlib routines using the VAX 
binding. VMS DECwindows provides the VAX binding for Xlib 
programmers who want to adhere to the VAX calling standard. For 
information about the standard, see the Introduction to VMS System 
Routines in the VMS operating system documentation set. 


The manual includes an overview of Xlib and tutorials that show how to 
use Xlib routines. 





Intended Audience 


This manual is intended for experienced programmers who need to learn 
graphics programming using Xlib routines. Readers should be familiar 
with a high-level language. The manual requires minimal knowledge of 
graphics programming. 





Document Structure 


This manual is organized as follows: 


¢ Chapter 1 provides an overview of Xlib, a sample Xlib program, and a 
guide to debugging Xlib programs. 


* Chapters 2 through 9 provide tutorials that show how to use Xlib 
routines and include descriptions of predefined Xlib data structures 
and code examples that illustrate the concepts described. 

This manual also includes the following appendixes: 

e Appendix A is a guide to using the VMS DECwindows font compiler. 


¢ Appendix B lists routines that require Xlib to issue protocol requests 
to the server. 


¢ Appendix C lists named VMS DECwindows colors. 
¢ Appendix D lists VMS DECwindows fonts. 





Associated Documents 


The following documents contain additional information: 


¢ VMS DECwindows Guide to Application Programming—Provides an 
overview of programming in the VMS DECwindows environment and 
a guide to programming the XUI Toolkit 


¢ VMS DECwindows Xlib Routines Reference Manual—Provides detailed 
descriptions of each Xlib routine 


e XUI Style Guide—Describes the standard VMS DECwindows user 
interface 
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Conventions 
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The following conventions are used in this manual: 


mouse 


MB1, MB2, MB3 


boldface text 


italic text 


UPPERCASE TEXT 


The term mouse is used to refer to any pointing 
device, such as a mouse, a puck, or a stylus. 


MB1 indicates the left mouse button, MB2 indicates 
the middle mouse button, and MB3 indicates the right 
mouse button. (The buttons can be redefined by the 
user.) 


A vertical ellipsis indicates the omission of items from 
a code example or command format; the items are 
omitted because they are not important to the topic 
being discussed. 


In format descriptions, brackets indicate that whatever 
is enclosed is optional; you can select none, one or 
all of the choices. 


Boldface text represents the introduction of a new 
term or the name of an argument, a constant, or a 
flag. 


Italic text represents a variable or a client-defined 
routine. 


Uppercase letters indicate the name of a routine or a 
system service call. 


1 Programming Overview of Xlib 


The VMS DECwindows programming environment includes Xlib, a library 
of low-level routines that enable the VMS DECwindows programmer to 
perform windowing and graphics operations. 


This chapter provides the following: 

e =©An overview of the library 

e A description of error handling conditions 

* Xlib debugging techniques 

Additionally, the chapter includes an introductory Xlib program. The 


program includes annotations that are explained more completely in the 
programming descriptions in later chapters of this guide. 





1.1 Overview of Xlib 


The VMS DECwindows programming environment enables application 
programs, called clients, to interact with workstations using the 

X Window System, Version 11 protocol. The program that controls 
workstation devices such as screens and pointing devices is the server. 
Xlib is a library of routines that enables a client to communicate with the 
server to create and manage the following: 


¢ Connections between clients and the server 

¢ Windows 

¢ Colors 

¢ Graphics characteristics such as line width and line style 

¢ Graphics 

¢ Cursors 

¢ Fonts and text 

¢ Pixmaps and offscreen images 

¢ Windowing and sending graphics between clients 

¢ Client notification of windowing and graphics operations 

Xlib processes some client requests, such as requests to measure the width 
of a character string, within the Xlib library. It sends other client requests, 


such as those pertaining to putting graphics on a screen or receiving device 
input, to the server. 


The server returns information to clients through either replies or events. 
Replies and events both return information to clients; the server returns 
replies synchronously and events asynchronously. 
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Programming Overview of Xlib 
1.1 Overview of Xlib 


Appendix B lists routines that cause Xlib to send requests to the server. 


Figure 1-1 illustrates the relationships among client, Xlib, and server. 
The client calls Xlib routines, which always reside on the client system. 
If possible, Xlib processes calls internally and returns information to 

the client when appropriate. When an Xlib function requires server 
intervention, Xlib generates a request and sends the request to the server. 


The server may or may not reside on the same system as the client 
and Xlib. In either case, Xlib communicates with the server through a 
transport protocol, which can be either local shared memory or DECnet. 


Figure 1-1 Client, Xlib, and Server 
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Messages Events ‘Ns 
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1.2 Sample Xlib Program 


The introductory Xlib program described in Example 1-1 illustrates the 
structure of a typical client program that uses Xlib windowing and graphic 
operations. The program creates two windows, draws text in one of them, 
and exits if the user clicks any mouse button while the cursor is in the 
window containing text. 


This section describes the program and introduces fundamental concepts 
about Xlib resources, windowing, and event-handling. 


1.2.1 ‘Initializing Xlib Resources 
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The sample program begins by creating Xlib resources that the client 
needs in order to perform tasks. Xlib resources include windows, fonts, 
pixmaps, cursors, color maps, and data structures that define the 
characteristics of graphics objects. The sample program uses a default 
font, default cursor, default color map, client-defined windows, and a 
client-defined data structure that specifies the characteristics of the text 
displayed. 


The program first makes a connection between the client and the server. 
The client-server connection is the display. After making the connection, 
or opening the display, the client can get display information from the 
server. For example, immediately after opening the display, the program 
calls the DEFAULT SCREEN OF DISPLAY routine to get the identifier of 


1.2.1.1 


1.2.1.2 


1.2.1.3 


1.2.1.4 
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the default screen. The program uses the identifier as an argument in a 
variety of routines it calls later. 


Creating Windows 
A window is an area of the screen that either receives input or both 
receives input and displays graphics. 


Windows in the X Window System are hierarchically related. At the base 
of the hierarchy is the root window. All windows that a client creates 
after opening a display are inferiors of the root window. The sample 
program includes two inferiors of the root window. First-generation 
inferiors of a window are its children. The root window has one child, 
identified in the sample as WINDOW_1. The window named WINDOW_2 
is an inferior of the root window and a child of WINDOW_1. 


To complete the window genealogy, all windows created before a specified 
window and hierarchically related to it are its ancestors. In the sample 
program, WINDOW_1 has one ancestor (the root window); WINDOW_2 has 
two ancestors (the root window and WINDOW_1). 


Defining Colors 

Defining background and foreground colors is part of the process 

of creating windows in the sample program. The DEFINE_COLOR 
subroutine allocates named VMS DECwindows colors for client use 

in a way that permits other clients to share the same color resource. 
For example, the routine specifies the VMS DECwindows color named 
“light grey” as the background color of WINDOW_2. If other clients were 
using VMS DECwindows color resources, they too could access the VMS 
DECwindows data structure that defines “light grey.” Sharing enables 
clients to use color resources efficiently. 


The program calls the DEFINE_COLOR subroutine again in the next 
step of initialization, creating the graphics context that defines the 
characteristics of a graphics object. In this case, the program defines 
foreground and background colors used when writing text. 


Working with the Window Manager 

Most clients run on systems that have a window manager, which is an Xlib 
application that controls conflicts between clients. The window manager 
also provides the user with control of the appearance of the window session 
screen. Clients provide the window manager with information about how 
it should treat client resources, although the manager can ignore the 
information. The sample program provides the window manager with 
information about the size and placement of WINDOW_1. Additionally, 
the program assigns a name that the window manager displays in the title 
bar of WINDOW_1. 


Making Windows Visible on the Screen 

Creating windows does not make them visible. To make its windows 
visible, a client must map them, painting the windows on a specified 
screen. The last step of initializing the sample program is to map 
WINDOW_1 and WINDOW_2. 
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Handling Events 
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The core of an Xlib program is a loop in which the client waits for the 
server to notify it of an event, which is a report of either a change in 
the state of a device or the execution of a routine call by another client. 
The server can report 30 types of events associated with the following 
occurrences: 


e Key presses and releases 

¢ Pointer motion 

¢ Window entries and exits 

e Changes of keyboards receiving input 

¢ Changes in keyboard configuration 

* Window and graphics exposures 

e Changes in window hierarchy and configuration 
¢ Requests by other clients to change windows 

e Changes in available color resources 


¢ Communication from other clients 


When an event occurs, the server sends information about the event to 
Xlib. Xlib stores the information in a data structure. If the client has 
specified an interest in that kind of event, Xlib puts the data structure on 
an event queue. The sample program polls the event queue to determine 
if it contains an event of interest to the client. When the program finds an 
event that is of interest to the client, the program performs a task. 


Because Xlib clients do their essential work in response to events, they are 
event driven. 


The sample program continually checks its event queue to determine if 
a window has been made visible or a button has been clicked. When the 
server informs it of either kind of event, the program performs its real 
work, as follows. 


If a window has been made visible, the server reports a window exposure 
event. Upon receiving this type of event, the program checks to determine 
whether or not the window exposed is WINDOW_2, and the event is the 
first instance of the exposure. If both conditions are true, the program 
writes a message into the window. 


If the event reported is a button press, the program checks to make certain 
the cursor was in WINDOW_2 when the user clicked the mouse button. If 
the user clicked the mouse button when the cursor was on the root window 
or WINDOW_1, the program reminds the user to click on WINDOW_2. 
Otherwise, the program initiates a series of shutdown routines. 


The shutdown routines unmap WINDOW_1 and WINDOW_2, free 
resources allocated for the windows, break the connection between the 
sample program and its server, and exit the system. 
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On the VMS operating system, clients only need to call SYS$EXIT. Exiting 
the system causes the other shutdown operations to occur. The call to 
SYS$EXIT breaks the connection between client and server, which frees 
resources allocated for client windows, and so forth. 


See Example 1-1 for the sample Xlib program. 


Example 1-1 Sample Program 





PROGRAM SAMPLE PROGRAM 


@°°0°0 


qaqa © 


INCLUDE ’SYSS$LIBRARY :DECWSXLIBDEF’ 


INTEGER*4 DPY 
INTEGER*4 SCREEN 
INTEGER*4 WINDOW_1, WINDOW _2 ! 
INTEGER*4 ATTR_MASK f 
INTEGER*4 GC ! 
INTEGER*4 FONT { 
INTEGER*4 DEFINE COLOR ! 
INTEGER*4 WINDOW _1X, WINDOW_1lyY ! 
INTEGER*4 DEPTH ! 
INTEGER*4 STATUS, FUNC ! 
INTEGER*4 STATE ! 


RECORD /XSVISUAL/ VISUAL 


RECORD /XSSET WIN ATTRIBUTES/ XSWDA 


RECORD /X$GC_VALUES/ XGCVL 
RECORD /X$SIZE_HINTS/ XSZHN 
RECORD /XSEVENT/ EVENT 


CHARACTER*19 WINDOW NAME 
DATA WINDOW_NAME /’Sample Xlib Program’ / 
CHARACTER*60 FONT NAME 
DATA FONT NAME 

1 /'-ADOBE-NEW CENTURY SCHOOLBOOK-MEDIUM-R-NORMAL~-*=140-*-—*-P—*/" / 
CHARACTER*19 MESSAGE (2) 
DATA MESSAGE /’Click here to exit ’, ’Click HERE to exit!// 


PARAMETER 
1 
1 


STATE = 1 


display id 
screen id 

window id 
attributes mask 
gc id 

font id 

color function 
window origin 
number of planes 
synchronous behavior 
flag for text 


! visual type 

! window attributes 
! gc values 

! hints 

! input event 


WINDOW_1W 
WINDOW 2w 
WINDOW 2X 


400, WINDOW_1H = 300, 
300, WINDOW_2H = 150, 
50, WINDOW_2¥ = 75 


Initialize display id and screen id 


DPY = X$OPEN_DISPLAY () 
IF (DPY .EQ. 0) THEN 


WRITE (6, *) 


CALL 
END IF 
SCREEN = 


‘Display not opened!’ 
SYSSEXIT (VAL (1) ) 


X$DEFAULT SCREEN _OF DISPLAY (DPY) 


STATUS = X$SYNCHRONIZE(DPY,1, FUNC) 


Create the WINDOW_1 window 


WINDOW_1X 


WINDOW_1Y = 


= (X$WIDTH_OF SCREEN(DPY) - WINDOW_iW) / 2 
(XSHEIGHT_OF_SCREEN(DPY) - WINDOW_1H) / 2 
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DEPTH = X$DEFAULT DEPTH OF SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. X$M_CW_BACK PIXEL 


XSWDA.X$L_SWDA_EVENT MASK = X$M EXPOSURE .OR. X$M_BUTTON_PRESS 
XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 1) 


3) WINDOW_1 = XSCREATE WINDOW (DPY, 
1 XS$ROOT_WINDOW_OF_ SCREEN (SCREEN) , 
1 WINDOW _1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 0, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 





Cc 
C Create the WINDOW_2 window 
c 
XSWDA.X$L_SWDA_BACKGROUND_ PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
WINDOW_2 = X$SCREATE WINDOW(DPY, WINDOW 1, 
1 WINDOW 2X, WINDOW_2Y, WINDOW _2W, WINDOW _2H, 4, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
Cc 
c Create graphics context 
Cc 
XGCVL.X$L_GCVL_FOREGROUND = ; 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 3) 
XGCVL.X$L_GCVL_BACKGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
4) GC = X$CREATE_GC(DPY, WINDOW 2, 
4 (XSM_GC_FOREGROUND .OR. X$M_GC_BACKGROUND), XGCVL) 
Cc 
Cc Load the font for text writing 
Cc 
8 FONT = X$LOAD_FONT(DPY, FONT_NAME) 
CALL X$SET_FONT(DPY, GC, FONT) 
C 
c Define the size and name of the WINDOW_1 window 
c 
XSZHN.XS$L_SZHN_X = 362 
XSZHN.X$L_SZHN Y = 282 
XSZHN.X$L_SZHN WIDTH = 400 
XSZHN.X$L_SZHN HEIGHT = 300 
XSZHN.XSL_SZHN FLAGS = X$M_P_ POSITION .OR. X$M_P_SIZE 
16) CALL X$SET_NORMAL HINTS (DPY, WINDOW 1, XSZHN) 
CALL XSSTORE_NAME(DPY, WINDOW _1, WINDOW NAME) 
c 
Cc Map the windows 
Cc 
7) CALL X$MAP_WINDOW(DPY, WINDOW_1) 


CALL X$MAP_WINDOW(DPY, WINDOW 2) 
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Example 1-1 (Cont.) Sample Program 


occa 


aqaqaa 


Oeroo 


eoo0ca 


Handle events 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 


If this is an expose event on our child window, 
then write the text. 


IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE .AND. 
1 EVENT.EVNT_EXPOSE.X$L_EXEV_ WINDOW .EQ. WINDOW _2 THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW_2) 
CALL X$DRAW_IMAGE_STRING(DPY, WINDOW_2, GC, 
1 75, 75, MESSAGE (STATE) ) 
END IF 


IF (EVENT.EVNT_TYPE .EQ. X$SC_BUTTON_PRESS) THEN 
IF (EVENT.EVNT_EXPOSE.X$L_EXEV_ WINDOW .EQ. WINDOW_1) THEN 


STATE = 2 
CALL X$DRAW_IMAGE_STRING(DPY, WINDOW 2, GC, 
1 75, 75, MESSAGE (STATE) ) 
ELSE 


Unmap and destroy windows 


CALL XSUNMAP_WINDOW(DPY, WINDOW_1) 
CALL X$DESTROY_WINDOW(DPY, WINDOW_1) 
CALL X$CLOSE_DISPLAY (DPY) 
CALL SYSSEXIT(%VAL(1)) 
END IF 
END IF 
END DO 


END 


Create color 


INTEGER*4 FUNCTION DEFINE COLOR(DISP, SCRN, VISU, N) 
INCLUDE ’ SYSSLIBRARY : DECW$XLIBDEF’ 


INTEGER*4 DISP, SCRN, N 

RECORD /XSVISUAL/ VISU 

RECORD /X$COLOR/ SCREEN_COLOR 

INTEGER*4 STR_SIZE, STATUS, COLOR_MAP 

CHARACTER*15 COLOR_NAME (3) 

DATA COLOR_NAME /’DARK SLATE BLUE’, ‘LIGHT GREY ‘, ‘FIREBRICK aa 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_COLOR .OR. 
1  VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT COLOR) THEN 
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COLOR_MAP = X$DEFAULT_COLORMAP_OF_ SCREEN (SCRN) 
STATUS = STRSTRIM(COLOR_NAME (N), 


1 COLOR_NAME(N), STR SIZE) 
STATUS = X$ALLOC_NAMED COLOR(DISP, COLOR_MAP, 
1 COLOR_NAME (N) (1:STR_SIZE), SCREEN_COLOR) 
IF (STATUS .NE. 0) THEN 
DEFINE COLOR = SCREEN_COLOR.X$L_COLR_PIXEL 
ELSE 
WRITE(6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL (VAL (STATUS) ) 
DEFINE COLOR = 0 
END IF 
ELSE 
IF (N .EQ. 1 .OR. N .EQ. 3) 
1 DEFINE_COLOR = X$BLACK_PIXEL_OF_SCREEN (DISP) 
IF (N .EQ. 2 ) 
1 DEFINE COLOR = XSWHITE PIXEL _OF_SCREEN (DISP) 
END IF 
RETURN 
END 


@ For information about connecting client and server, see Chapter 2. 


@ Xlib buffers client requests and sends them to the server 
asynchronously. This causes clients to receive errors after they have 
occurred. When debugging a program, call the SYNCHRONIZE 
routine to enable synchronous error reporting. Using the 
SYNCHRONIZE routine has a serious negative effect on performance. 
Clients should call the routine only when debugging. For more 
information about debugging, see Section 1.4. 


© For information about creating windows, see Chapter 3. 


@ Before drawing a graphics object on the screen, clients must define the 
characteristics of the object. The program defines the foreground and 
background values for writing text. For information about defining 
graphics characteristics, see Chapter 4. 


@ The sample program loads a VMS DECwindows font, New Century 
Schoolbook Roman 14, which the program uses to write the text in 
WINDOW_2. For information about loading fonts, see Chapter 8. 


© The program provides the window manager with hints about window 
size and position. For more information about window management, 
see Section 3.5.1. 


@ Mapping windows makes them visible on the screen. For information 
about window mapping, see Chapter 3 


For more information about event handling, see Chapter 9. 


When a client exits a VMS DECwindows program on the VMS 
operating system, the series of calls to unmap and destroy windows 
and close the display occurs automatically. 
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@ VMS DECwindows includes named colors for the convenience of 
clients. The sample program uses the named colors “dark slate blue,” 
“light grey,” and “firebrick.” It shares the named colors it uses with 
other clients. For information about sharing colors, whether named or 
client-defined, see Chapter 5. For information about defining colors for 
exclusive use, see Section 5.4. For a list of named VMS DECwindows 
colors, see Appendix C. 


1.3 Handling Error Conditions 


Xlib differs from most VMS programming libraries in the way it handles 
error conditions. In particular, Xlib does not perform any validation of 
input arguments when an Xlib routine is called. 


If the input arguments are incorrect, the server usually generates an error 
event when it receives the Xlib request. Unless the client has specified 
an error handler, the server invokes the default Xlib error handler, which 
prints out a diagnostic message and exits. For more information about the 
Xlib error handler, refer to Section 9.13.2. 


In some cases, Xlib signals a fatal access violation (SYS-F-ACCVIO) when 
passed incorrect arguments. This occurs when arguments are missing or 
are passed using the wrong addressing mode (passed by value instead of 
passed by reference). 





1.4 Debugging Xlib Programs 


As noted in Section 1.1, Xlib handles client requests asynchronously. 
Instead of dispatching requests as it receives them, Xlib buffers requests 
to increase communication efficiency. 


Buffering contributes to delays in error reporting. Asynchronous reporting 
enables Xlib and the server to continue processing client requests despite 
the occurrence of errors. However, buffering contributes to the delay 
between the occurrence and client notification of an error. 


As a result, programmers who want to step through routines to 

locate errors must override the buffering that causes asynchronous 
communication between client and server. To override buffering, use 

the SYNCHRONIZE routine. Example 1-1 includes a SYNCHRONIZE 
call as a debugging tool. Use the SYNC routine if you are interested in a 
specific call. The SYNC routine flushes the output buffer and then waits 
until all requests have been processed. 


2 Managing the Client-Server Connection 


A client requires one or more servers to process requests and return 
keyboard and mouse input. The server can be located either on the same 
system as the client or at a remote location where it is accessed across a 
network. 


This chapter describes the following topics related to managing the client- 
server connection: 


¢ Overview of the client-server connection 
¢ Opening and closing a display 
¢ Getting information about a display 


e Managing sending requests to the server 


2.1 Overview of the Client-Server Connection 


A client using Xlib makes its first call to open a display. After opening a 
display, the client can get display information from and send requests to 
the server. To increase the efficiency of the client-server connection, Xlib 
buffers client requests. 


To understand the relationship between a display and hardware, consider 
the classroom illustrated in Figure 2-1. The server and an instructor 
client program are running on the instructor VAXstation, which includes a 
screen, a keyboard, and a mouse. When the instructor opens a display, 
Xlib establishes a connection between the instructor client program 

and the server. The instructor can output graphics on the instructor 
VAXstation screen. 
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Figure 2-1 Graphics Output to Instructor VAXstation 
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If the instructor wants to output graphics to student screens, each student 
VAXstation must be running a server, and the client program must be 
connected to each server, as Figure 2—2 illustrates. Unlike the prior 
example, where the client program opened one display by making an 
internal connection with the server running on the VAXstation, here the 
client program establishes connections with multiple servers. 


Xlib also enables multiple clients to establish connections with one server. 
For example, to output student work on the instructor screen, each 
student must open a display with the server running on the instructor 
VAXstation. 
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Figure 2-2 Graphics Output to Student VAXstations 
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Establishing the Client-Server Connection 


The OPEN DISPLAY routine establishes a connection between the client 
and the server. The OPEN DISPLAY routine call has the following format: 
display = XSOPEN_DISPLAY (display_name) 

In this call, display_name is a string that specifies the node on which 
the server is running and the transport mechanism used to make the 
connection between the client and the server. If the transport mechanism 
is local shared memory, users should use the DCL command SET DISPLAY 
to define which display to open and pass a null argument to the OPEN 
DISPLAY routine. The null argument causes the server to search for 

the definition of the display. If the transport mechanism is DECnet, the 
display_name argument has the following format: 


hostname: :number.screen 


The elements of the argument are as follows: 
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Elements Description 

hostname The host on which the server is running. The double colons indicate 
that the transport mechanism is DECnet. 

number The number of the display on the host machine. If the client and 


server are physically running in the same CPU, clients can specify a 
display number of zero, which causes the transport to use a version 
of DECnet that optimizes local performance. 


screen The screen on which client input and output is handled. 


See Example 1-1 for an example of defining a display. 
If successful, OPEN DISPLAY returns a unique identifier of the display. 


Refer to the VMS DECwindows User’s Guide for more information about 
specifying a display. 


2.3 Closing the Client-Server Connection 
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Although Xlib automatically destroys windows and resources related to 

a process when the process exits the server, clients should close their 
connection with a server explicitly. Clients can close the connection using 
the CLOSE DISPLAY routine. CLOSE DISPLAY destroys all windows 
associated with the display and all resources the client has allocated. The 
CLOSE DISPLAY routine call has the following format: 


XSCLOSE_DISPLAY (display) 
For an example of closing a display, see Example 1-1. 


After closing a display, clients should not refer to windows, identifiers, and 
other resources associated with that display. 


When a display is closed automatically or by an explicit call to CLOSE 
DISPLAY, the server does the following: 


¢ Discards all input events selected by the client. For information about 
input events, see Chapter 9. 


¢ Ifthe client has marked the keyboard, specific keys, the pointer button, 
the pointer, or the server for its exclusive use, the server releases them 
for use by other clients. 


¢ Determines what happens to client resources after the display is 
closed. 


If the server is to destroy all client resources, it destroys them as follows: 


e Examines each window in the client save set. The save set is a list of 
windows that other clients are using. If a window is a member of the 
save set, the server reparents the window to an ancestor not created 
by the client. 


¢ Maps the save set window, if it is unmapped. The server does this 
even if the save set window was not a subwindow of a window created 
by the client. 


¢ Destroys all windows created by the client after examining each in the 
client save set. 
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e Frees each nonwindow resource (font, pixmap, cursor, color map, and 
graphics context) created by the client. 


¢ Frees all colors and color map entries allocated by the client. 


When the last connection to the server closes and the server is to destroy 
all client resources, the server performs the following additional steps: 


¢ Resets its state as if it had just been started 


¢ Deletes all identifiers except predefined names of window 
characteristics 


¢ Deletes all information associated with the root window 


* Resets all device maps and attributes (key click, bell volume, 
acceleration) and the server access control list, a list of hosts 
that can run client programs 


e¢ Restores the standard cursors and root tile, which is a pixmap 
replicated to create a window background 


¢ Restores the default font path 


¢ Restores input focus to the root window 


The server does not perform reset operations if a client requests the server 
to retain its resources. 


Refer to the VMS DECwindows Xlib Routines Reference Manual for 
information about the SET CLOSE DOWN MODE routine. 


2.4 Getting Information About the Client-Server Connection 


After opening a display, clients can get information about the client-server 
connection using routines listed in Table 2-1. Clients can get information 
about client screens using routines listed in Table 2-2. Clients can get 
information about images created on screens using routines listed and 
described in Table 2-3. 


These routines are useful for supplying arguments to other routines. 
See the VMS DECwindows Xlib Routines Reference Manual for the 
syntax of information routines. Programming examples throughout 
this programming guide provide examples and descriptions of the use 
of information routines. 


Table 2-1 Client-Server Connection Routines 


Routine Value returned 

ALL PLANES All bits set on. Used as a plane argument to a 
routine. 

BLACK PIXEL Pixel value that yields black on the specified 
screen. 


(continued on next page) 
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Table 2-1 (Cont.) Client-Server Connection Routines 


Routine 


CONNECTION NUMBER 
DEFAULT COLORMAP 


DEFAULT DEPTH 


DEFAULT GC 


DEFAULT ROOT WINDOW 
DEFAULT SCREEN 


DEFAULT VISUAL 


DISPLAY CELLS 


DISPLAY PLANES 
DISPLAY STRING 


IMAGE BYTE ORDER 


PROTOCOL REVISION 


PROTOCOL VERSION 


Q LENGTH 


ROOT WINDOW 


SCREEN COUNT 
SERVER VENDOR 


VENDOR RELEASE 


WHITE PIXEL 


Value returned 


Connection number of the specified display. 


Identifier of the default color map for allocation 
on the specified screen. 


Depth in planes of the default root window for 
the specified screen. 


Default graphics context for the root window of 
the specified screen. 


Default root window for the specified screen. 


Default screen referred to by the OPEN 
DISPLAY routine. 


Default visual data structure for the specified 
screen. 


Number of color map entries on the specified 
screen. 


Number of planes on the specified screen. 


String passed when the display was opened. 
The string takes the form 0::NAME. 


Byte order for images for each scanline unit in 
XY format (bitmap) or for each pixel value in 
Z format. If byte order is least most significant 
bit first, the server returns the constant x$c_ 
Isb_first. If the byte order is most significant 
bit first, the server returns the constant x$c_. 
msb_first. 


Minor protocol revision number that the server 
is using. 

Version number of the protocol associated with 
the display. 


Length of the event queue for the display. 
There may be events that the server has not 
put on the queue. 


Identifier of the root window. 
Number of available screens. 


Identifier of the owner of the server 
implementation. 


Release number of the server, which is 
assigned by the vendor. 


Pixel value that yields white on the specified 
screen. 
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Table 2-2 Screen Routines 


Routine 


Value Returned 





BLACK PIXEL OF SCREEN 
CELLS OF SCREEN 


DEFAULT COLORMAP OF SCREEN 


DEFAULT DEPTH OF SCREEN 
DEFAULT GC OF SCREEN 


DEFAULT SCREEN OF DISPLAY 
DEFAULT VISUAL OF DISPLAY 
DOES BACKING STORE 

DOES SAVE UNDERS 


DISPLAY OF SCREEN 
EVENT MASK OF SCREEN 
HEIGHT OF SCREEN 
HEIGHT MM OF SCREEN 
MAX CMAPS OF SCREEN 


MIN CMAPS OF SCREEN 


PLANES OF SCREEN 

ROOT WINDOW OF SCREEN 
SCREEN OF DISPLAY 
WHITE PIXEL OF SCREEN 
WIDTH OF SCREEN 

WIDTH MM OF SCREEN 


Black pixel value of the specified screen. 


Number of color map entries for the specified 
screen. 


Identifier of the default color map of the 
specified screen. 


Depth in planes of the specified screen. 


Default graphics context of the specified 
screen. 


Default screen of display. 
Default visual type of display. 
Backing store is not supported in this release. 


Either true or false. True indicates the server 
saves the contents of windows that the client 
window obscures. 


Display of the screen. 

Root event mask of the screen. 
Height of screen in pixels. 
Height of screen in millimeters. 


Maximum number of color maps supported by 
the screen. 


Minimum number of color maps supported by 
the screen. 


Number of planes on the screen. 

Root window on the screen. 

Identifier of the specified screen. 

White pixel value of the specified screen. 
Width of the screen in pixels. 

Width of the screen in millimeters. 


Table 2-3 Image Format Routines 


Routine 


BITMAP BIT ORDER 


BITMAP PAD 
BITMAP UNIT 
DISPLAY HEIGHT 


Value Returned 


The leftmost bit in a bitmap can be either 

the least or most significant bit. This routine 
returns either the constant x$c_Isb_first or the 
constant x$c_msb_first. 


Number of bits by which scanlines are padded. 
Size in bits of a bitmap unit. 
Height of the screen in pixels. 
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Table 2-3 (Cont.) Image Format Routines 





Routine Value Returned 

DISPLAY HEIGHT MM Height of the screen in millimeters. 

DISPLAY WIDTH Width of the display in pixels. 

DISPLAY WIDTH MM Width of the display in millimeters. 
2.5 Managing Requests to the Server 
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Instead of sending each request to the server as the client specifies the 
request, Xlib buffers requests and sends them as a block to increase 
the efficiency of client-to-server communication. The routines listed in 
Table 2-4 control how requests are output from the buffer. 


Table 2-4 Output Buffer Routines 


Routine Description 
FLUSH Fiushes the buffer. 
SET AFTER FUNCTION Specifies the function the client calls after 


processing each protocol request. 


SYNC Flushes the buffer and waits until the server 
has received and processed all events, 
including errors. Use SYNC to isolate one call 
when debugging. 

SYNCHRONIZE Causes the server to process requests in the 
buffer synchronously. SYNCHRONIZE causes 
Xlib to generate a return after each Xlib routine 
completes. Use it to debug an entire client or 
block. 


Most clients do not need to call the FLUSH routine because the output 
buffer is automatically flushed by calls to event management routines. 
Refer to Chapter 9 for more information about event handling. 


3 Working with Windows 


Windows receive information from users; they display graphics, text, and 
messages. Xlib enables a client to create multiple windows and define 
window size, location, and visual appearance on one or more screens. 


Conflicts between clients about displaying windows are handled by a 
window manager, which controls the size and placement of windows and, 
in some cases, window characteristics such as title bars and borders. The 
window manager also keeps clients informed about what it is doing with 
their windows. For example, the window manager might tell a client 
that one of its windows has been resized so that the client can reformat 
information displayed in the window. 


This chapter describes the following topics related to windows and the 
window manager: 


¢ Window fundamentals—A discussion of window type, hierarchy, 
position, and visibility 


¢ Creating and destroying windows—-How to create and destroy windows 


¢ Working with the window manager—How to work with the window 
manager to define user information concerning window management 


¢ Mapping and unmapping windows—How to make windows visible on 
the screen 


¢ Changing window characteristics—How to change the size, position, 
stacking order, and attributes of windows 


¢ Getting information about windows—How to get information about 
window hierarchies, attributes, and geometry 





3.1 Window Fundamentals 


A window is an area of the screen that either receives input or receives 
input and displays graphics. 


One type of window only receives input. Because an input-only window 
does not display text or graphics, it is not visible on the screen. Clients 
can use input-only windows to control cursors, manage input, and define 
regions in which the pointer is used exclusively by one client. 


A second type of window both receives input and displays text and 
graphics. 


Clients can make input-output windows visible on the screen. To make 

a window visible, a client first creates the window and then maps it. 
Mapping a window allows it to become visible on the screen. When more 
than one window is mapped, the windows may overlap. Window hierarchy 
and position on the screen determine whether or not one window hides the 
contents of another window. 
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Window Hierarchy 


Windows that clients create are part of a window hierarchy. The hierarchy 
determines how windows are seen. At the base of the hierarchy is the root 
window, which covers the entire screen when the client opens a display. 
All windows created after opening a display are subwindows of the root 
window. 


When a client creates one or more subwindows of the root window, the root 
window becomes a parent. Children of the root window become parents 
when clients create subwindows of the children. 


The hierarchy is structured like a stack of papers. At the bottom of the 
stack is the root window. Windows that clients create after opening a 
display are stacked on top of the root window, overlapping parts of it. 
For example, the window named child-of-root overlaps parts of the root 
window in Figure 3-1. The child-of-root window always touches the root 
window. Xlib always stacks children on top of the parents. 


Figure 3-1 Root Window and One Child 


Child—of-root 





ZK-0004A-GE 
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If a window has more than one child and if their borders intersect, Xlib 
stacks siblings in the order the client creates them, with the last sibling on 
top. For example, the second-level window named 2nd-child-of-root, which 
was created last, overlaps the second-level window named 1st-child-of-root 
in Figure 3-2. 
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Figure 3-2 Relationship Between Second-Level Windows 
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2nd-child—of-root 


Root 
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Third-level windows maintain the hierarchical relationships of their 
parents. The child-of-1st-child window overlaps child-of-2nd-child in 
Figure 3-3. 
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Windows created before a specified window and hierarchically related to 
it are ancestors of that window. For example, the root window and the 
window named Ist-child-of-root are ancestors of child-of-1st-child-of-root. 


3.1.2 Window Position 


Xlib coordinates define window position on a screen and place graphics 
within windows. Coordinates that specify the position of a window 

are relative to the origin, the upper left corner of the parent window. 
Coordinates that specify the position of a graphic object within a window 
are relative to the origin of the window in which the graphic object is 
displayed. 


Xlib measures length along the x axis from the origin to the right; it 
measures length along the y axis from the origin down. Xlib specifies 
coordinates in units of pixels, the smallest unit the server can display on 
a screen. Figure 3—4 illustrates the Xlib coordinate system. 
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Figure 3-4 Coordinate System 
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For more information about positioning windows, see Section 3.2. For 
more information about positioning graphics, see Chapter 6. 


3.1.3. Window Visibility and Occlusion 


A window is visible if one can see it on the screen. To be visible, a window 
must be an input-output window, it must be mapped, its ancestors must 

be mapped, and it must not be totally hidden by another window. When a 
window and its ancestors are mapped, the window is considered viewable. 
A viewable window that is totally hidden by another window is not visible. 


Even though input-only windows are never visible, they can overlap 
other windows. An input-only window that overlaps another window 
is considered to occlude that window. Specifically, window A occludes 
window B if both are mapped, if A is higher in the stacking order than 
B, and if the rectangle defined by the outside edges of A intersects the 
rectangle defined by the outside edges of B. 


A viewable input-output window that overlaps another window is 
considered to obscure that window. Specifically, window A obscures 
window B if Ais a viewable input-output window, if A is higher in the 
stacking order than B, and if the rectangle defined by the outside edges of 
A intersects the rectangle defined by the outside edges of B. 
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Creating Windows 


After opening a display, clients can create windows. As noted in the 
description of window fundamentals (Section 3.1), creating a window does 
not make it visible on a screen. To be visible, the window must meet the 
conditions described in Section 3.1.3. 


Clients can either create windows that inherit most characteristics not 
relating to size or shape from their parents or define all characteristics 
when creating windows. 


Using Attributes of the Parent Window 
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An attribute is a characteristic of a window not relating to size or shape, 
such as the window background color. The CREATE SIMPLE WINDOW 
routine creates an input-output subwindow that inherits the following 
attributes from its parent: 


¢ Method of moving the contents of a window when the parent is moved 
or resized 


* Instructions for saving window contents when the window obscures or 
is obscured by another window 


¢ Instructions to the server regarding information that ancestors should 
know when a window change occurs 


¢ Instructions to the window manager concerning map requests 
* Color 


¢ Cursor 


For more information about these attributes, see Section 3.2.2. 


If the parent is a root window, the new window created with the CREATE 
SIMPLE WINDOW routine has the following attributes: 


¢ The server discards window contents if the window is reconfigured. 
¢ The server discards the contents of obscured portions of the window. 


¢ The server discards the contents of any window that the new window 
obscures. 


* No events are specified as being of interest to the window ancestors. 
¢ No restrictions are placed on the window manager. 
* The color is identical to the parent color. 


¢ No cursor is specified. 


In addition to creating a window with attributes inherited from the parent 
window, the CREATE SIMPLE WINDOW routine enables clients to define 
the border and background attributes of the window and its position and 
size. 
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Example 3-1 illustrates creating a simple window. To make the window 
visible, the example includes mapping and event handling functions, which 
are described in Section 3.4 and Chapter 9. 


Example 3-1 Creating a Simple Window 
INTEGER*4 WINDOW 1 
INTEGER*4 WINDOW_1X, WINDOW_1yY 


0 PARAMETER WINDOW _1W = 600, WINDOW_1H = 600 


WINDOW_1X = (XSDISPLAY WIDTH_OF_SCREEN(SCREEN) - WINDOW_1W) / 2 
WINDOW_1Y = (X$DISPLAY_HEIGHT_OF_SCREEN (SCREEN) - WINDOW_1H) / 2 


WINDOW _1 = X$CREATE SIMPLE WINDOW (DPY, 

1  X$ROOT_WINDOW_OF_ SCREEN (SCREEN) , 

1 WINDOW _1X, WINDOW_lY, WINDOW_1W, WINDOW_1H, 10, 

1 XS$BLACK_PIXEL_OF_SCREEN (SCREEN), X$WHITE PIXEL OF_SCREEN (SCREEN) ) 


@ Assign window width and height the value of 600 (pixels) each. 


@ The client specifies the position of the window using two display 
information routines, DISPLAY WIDTH and DISPLAY HEIGHT. 
The WINDOW_1X and WINDOW_1Y coordinates define the top left 
outside corner of the window borders relative to the inside of the 
parent border. In this case, the parent is the root window, which does 
not have a border. 


© The CREATE SIMPLE WINDOW routine call has the following format: 
window_id = XSCREATE SIMPLE WINDOW(display, parent_id, 
x coord, y coord, width, height, border width, 
border_id, background_id) 


The client specifies a black border ten pixels wide, a white background, 
and a size of 600 by 600 pixels. 


The window manager overrides border width and color. 


CREATE SIMPLE WINDOW returns a unique identifier, WINDOW_1, 
used in subsequent calls related to the window. 


3.2.2 Defining Window Attributes 


To create a window whose attributes are different from the parent window, 
use the CREATE WINDOW routine. The CREATE WINDOW routine 


enables clients to specify the following window attributes when creating 
an input-output window: 


¢ Default contents of an input-output window 
* Border of an input-output window 


¢ Treatment of the window when it or its relative is obscured 
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¢ Treatment of the window when it or its relative is moved 


¢ Information the window receives about operations associated with 
other windows 


¢ Color 


¢ Cursor 


Clients creating input-only windows can define the following attributes: 
¢ Treatment of the window when it or its relative is moved 


¢ Information the window receives about operations associated with 
other windows 


¢ Cursor 
Specifying other attributes for an input-only window causes the server to 


generate an error. Input-only windows cannot have input-output windows 
as children. 


Use the following method to define window attributes: 


¢ Assign values to the relevant members of a set window attributes data 
structure. 


¢ Indicate the defined attribute by specifying the appropriate flag and in 
the value_mask argument of the CREATE WINDOW routine. If more 
than one attribute is to be defined, indicate the attributes by doing 
a bitwise OR on the appropriate flags and passing the result in the 
value_mask argument of the CREATE WINDOW routine. 


Figure 3-5 illustrates the set window attributes data structure. 
Figure 3-5 Set Window Attributes Data Structure 
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Figure 3—5 (Cont.) Set Window Atiributes Data Structure 
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Table 3-1 describes the members of the data structure. 
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Table 3-1 Set Window Attributes Data Structure Members 


Member Name Conients 


X$L_SWDA_BACKGROUND_PIXMAP Defines the window background of an input-output window. This 
member can assume one of three possible values: pixmap identifier, 
the constant x$c_none (default), or the constant x$c_parent_relative. 


If the client specifies a pixmap identifier, a pixmap defines the 
window background. The pixmap must have the same root and 
number of bits per pixel as the window but can be any size. For 
more information about creating pixmaps, see Chapter 7. 


If the client specifies the constant x$c_none (the default), the 
window has no defined background. If the parent has no defined 
background, neither does the window being created. 


lf the client specifies the constant x$c_parent_relative, the 
background of the window is identical to the background of its 
parent. In this case, the window must have the same number of 
bits per pixel as the parent. If the background value of the window 
is x$c_parent_relative and the parent background is x$c_none, the 
window being created has no defined background. 


(continued on next page) 
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Table 3-1 (Cont.) Set Window Attributes Data Structure Members 


Member Name Conients 


The server does not copy the parent background; instead, it 
reexamines the parent background each time the client needs 
the window background. For a background that is identical to the 
parent background, the origin of the background tile always aligns 
with the origin of the parent background tile origin. Otherwise, the 
background tile origin is always the window origin. 


If the client alters the pixmap after using it for the background, the 
results are unpredictable because the server might either make a 
copy of the pixmap used to draw the background, or it might refer to 
the pixmap directly. Free the background pixmap when the client no 
longer needs to refer to it. In particular, free the pixmap after setting 
it into the window but before destroying the window. 


When regions of the window are exposed and the server has not 
retained their contents, the server automatically tiles the regions with 
the background pixmap if the client specified a pixmap identifier or 
the constant x$c_parent_relative. If the client specified the constant 
x$c_none, the server leaves the previous screen contents in place, 
provided the window and its parent have the same number of bits 
per pixel. Otherwise, the initial contents of the exposed region are 
undefined. 


X$L_SWDA_BACKGROUND_ PIXEL Specifying a value for the X$L_SWDA_BACKGROUND_ 
PIXEL member causes the server to override the X$L_SWDA_ 
BACKGROUND_PIXMAP member. This is equivalent to specifying a 
pixmap of any size filled with the background pixel and used to paint 
the window background. 


X$L_SWDA_BORDER_PIXMAP Defines the window border of an input-output window. The following 
conditions apply: 


* The border tile origin is always the same as the background tile 
origin. 

* The border pixmap and the window must have the same root 
and the same number of bits per pixel. Otherwise, the server 
issues an error. 


* Clients can specify a pixmap of any size. Using some sizes, 
however, increases performance. 


« The default copies the border pixmap from the parent. If the 
client specifies the constant x$c_copy_from_parent, the parent 
border pixmap is copied. The window must have the same 
number of bits per pixel as the parent, or the server issues an 
error. Subsequent changes to the parent do not affect the child. 


lf the client alters the pixmap after using it for the border, the results 
are unpredictable because the server may either make a copy of 
the pixmap used to draw the border, or it may refer to the pixmap 
directly. 


Because output to a window is always limited or clipped to the inside 
of the window, graphics operations are never affected by the window 
border. 





(continued on next page) 
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Table 3—1 (Cont.) Set Window Attributes Data Structure Members 


Member Name 


X$L_SWDA_BORDER_PIXEL 


X$L_SWDA_BIT_GRAVITY 


X$L_SWDA_WIN_GRAVITY 


X$L_SWDA_BACKING_STORE 


X$L_SWDA_BACKING_PLANES 


X$L_SWDA_BACKING_PIXEL 


X$L_SWDA_SAVE_UNDER 


Contents 


Specifying a value for X$L_SWDA_BORDER_PIXEL causes the 
server to override the X$L__SWDA_BORDER_PIXMAP member. This 
is equivalent to specifying a pixmap of any size filled with the border 
pixel and used to paint the window border. 


Defines how window contents should be moved when an input-only 
or input-output window is resized. By default, the server does not 
retain window contents. For more information about bit gravity, see 
Section 3.6. 


Defines how the server should reposition the newly created input- 
only or input-output window when its parent window is resized. By 
default, the server does not move the newly created window. For 
more information about window gravity, see Section 3.6. 


Provides a hint to the server about how the client wants it to manage 
obscured portions of the window. In this release, clients must 
maintain window contents. 


Indicates (with bits set to one) which bit planes of the window hold 
dynamic data that must be preserved if the window obscures or is 
obscured by another window. !n this release, clients must maintain 
data to be preserved. 


Defines what values to use in planes not specified by the X$L_ 
SWDA_BACKING_PLANES member. In this release, clients must 
maintain values. 


Setting the X$L_SWDA_SAVE_UNDER member to true informs the 
server that the client would like the contents of the screen saved 
when an input-output window obscures them. Clients must maintain 
the contents of screens. 


(continued on next page) 
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Table 3-1 (Cont.) Set Window Attributes Data Structure Members 


Member Name Contents 


X$L_SWDA_EVENT_MASK Defines which types of events associated with an input-only or 
input-output window the server should report to the client. For more 
information about defining event types, see Chapter 9. Following are 
events about which the client can state an interest: 


Event Type Description 
Button Motion, button press and release, 
exclusive input 
Color Change in color map 
Window Eniry into and exit from a window 
Exposure Exposure of a previously obscured 
window 
Input focus Change in window that receives keyboard 
input 
Keyboard and keys Change in keyboard state, and key press 
or release 
Pointer Motion 
Property Change in window characteristics 
Structure Notification and contro! of requests from 
clients 
X$L_SWDA_DO_NOT_PROPAGATE _ Defines which kinds of events should not be propagated to 
MASK ancestors. For more information about managing events, see 
Chapter 9. 
X$L_SWDA_OVERRIDE_REDIRECT Specifies whether calls to map and configure an input-only or 


input-output window should override a request by another client to 
redirect those calls. For more information about redirecting calls, see 
Chapter 9. Typically, this is used to inform a window manager not 
to tamper with the window, such as when the client is creating and 
mapping a menu. 


X$L_SWDA_COLORMAP Specifies the color map, if any, that best reflects the colors of an 
input-output window. The color map must have the same visual type 
as the window. If it does not, the server issues an error. For more 
information about the color map and visual types, see Chapter 5. 


X$L_SWDA_CURSOR Specifying a value for the cursor member causes the server to use a 
particular cursor when the pointer is in an input-only or input-output 
window. 





Table 3—2 lists default values for the set window attributes data 
structure. 
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Table 3-2 Default Values of the Set Window Attributes Data Structure 





Member 


X$L_SWDA_BACKGROUND_PIXMAP 
X$L_SWDA_BACKGROUND_PIXEL 
X$L_SWDA_BORDER_PIXMAP 
X$L_SWDA_BORDER_PIXEL 
X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 
X$L_SWDA_BACKING_STORE 
X$L_SWDA_BACKING_PLANES 
X$L_SWDA_BACKING_PIXEL 
X$L_SWDA_SAVE_UNDER 
X$L_SWDA_EVENT_MASK 


X$L_SWDA_DO_NOT_PROPAGATE_ 
MASK 


X$L_SWDA_OVERRIDE_REDIRECT 
X$L_SWDA_COLORMAP 
X$L_SWDA_CURSOR 


Default Value 


None 

Undefined 

Copied from the parent window 
Undefined 

Window contents not retained 
Window not moved 

Window contents not retained 
All 1s 

0 

False 

Empty set 

Empty set 


False 
Copied from parent 
None 


Xlib assigns a flag for each member of the set window attributes data 
structure to facilitate referring to the members, as listed in Table 3-3. 


Table 3-3 Set Window Attributes Data Structure Flags 


Flag Name 


x$m_cw_back_pixmap 
x$m_cw_background_pixel 
x$m_cw_border_pixmap 
x$m_cw_border_pixel 
x$m_cw_bit_gravity 
x$m_cw_win_gravity 
x$m_cw_backing_store 
x$m_cw_backing_planes 
x$m_cw_backing_pixel 
x$m_cw_override_redirect 
x$m_cw_save_under 
x$m_cw_event_mask 


Set Window Attributes Member 


X$L_SWDA_BACKGROUND_PIXMAP 
X$L_SWDA_BACKGROUND_PIXEL 
X$L_SWDA_BORDER_PIXMAP 
X$L_SWDA_BORDER_PIXEL 
X$L_SWDA_BIT_GRAVITY 
X$L_SWDA_WIN_GRAVITY 
X$L_SWDA_BACKING_STORE 
X$L_SWDA_BACKING_PLANES 
X$L_SWDA_BACKING_PIXEL 
X$L_SWDA_OVERRIDE_REDIRECT 
X$L_SWDA_SAVE_UNDER 
X$L_SWDA_EVENT_MASK 





(continued on next page) 
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Table 3-3 (Cont.) Set Window Attributes Data Structure Flags 





Flag Name Set Window Attributes Member 
x$m_cw_dont_propagate X$L_SWDA_DO_NOT_PROPAGATE_MASK 
x$m_cw_colormap X$L_SWDA_COLORMAP 

x$m_cw_cursor X$L_SWDA_CURSOR 


Note that in addition to the mask symbols (x$m_) listed in Table 3-3, the 
Xlib definition files also define the corresponding bit field symbols (x$v_). 


Example 3—2 illustrates how clients can define window attributes while 
creating input-output windows with the CREATE WINDOW routine. 
The program creates a parent window and two children windows. The 
hierarchy of the subwindows is determined by the order in which the 
program creates them. In this case, SUBWINDOW_1 is superior to 
SUBWINDOW_2, which is created last. 


Example 3-2 Defining Attributes When Creating Windows 





INTEGER*4 WINDOW ! window id 
INTEGER*4 SUBWINDOW_1 ! window id 
INTEGER*4 SUBWINDOW_2 ! window id 


RECORD /XS$SET_WIN_ATTRIBUTES/ XSWDA ! window attributes 


PARAMETER WINDOW_W = 600, WINDOW_H = 600, 

1 SUBWINDOW_1X 150, SUBWINDOW_1Y¥ = 
SUBWINDOW 1W 300, SUBWINDOW_1H = 

SUBWINDOW_2X 275, SUBWINDOW_2Y = 

SUBWINDOW_2W 50, SUBWINDOW_2H = 1 


noun wl 


PRR 


WINDOW X 


ie (XSWIDTH_OF_SCREEN(SCREEN) - WINDOW _W) / 2 
WINDOW_Y 


(X$HEIGHT OF SCREEN (SCREEN) - WINDOW_H) / 2 


DEPTH = XSDEFAULT_DEPTH OF SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. XSM_CW_BACK_PIXEL 


© 


XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON_PRESS 
XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 1) 


© 


WINDOW = X$CREATE_WINDOW (DPY, 

1  X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 

1  WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H, 0, 

1 DEPTH, X$C_INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Create the SUBWINDOW_1 window 


aqgaaa 


XSWDA.XSL_SWDA_BACKGROUND_PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 2) 
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Example 3-2 (Cont.) Defining Attributes When Creating Windows 





aaa 


SUBWINDOW_1 = XS$CREATE WINDOW (DPY, WINDOW, 
1 SUBWINDOW_1X, SUBWINDOW_1Y, SUBWINDOW_1W, SUBWINDOW_1H, 4, 
1 DEPTH, X$C_INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Create the SUBWINDOW_2 window 


XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 3) 


SUBWINDOW_2 = X$CREATE WINDOW (DPY, WINDOW, 
1 SUBWINDOW_2X, SUBWINDOW_2Y, SUBWINDOW_2W, SUBWINDOW_2H, 4, 
al DEPTH, X$C_INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


INTEGER*4 FUNCTION DEFINE COLOR(DISP, SCRN, VISU, N) 


@ Allocate storage for a set windew attributes data structure used to 
define window attributes. 


@ Set the attributes of the parent window. The client indicates an 
interest in window exposure and button press events. For more 
information about events, see Chapter 9. 


The client defines window background by calling the DEFINE_COLOR 
routine. For more information about defining colors, see Chapter 5. 


© The CREATE WINDOW routine call has the following format: 


window_id_return=X$CREATE_WINDOW(display, parent_id, 
x_coord, y coord, width, height, border_width, 
depth, class, visual_struc, attributes_mask, 
attributes) 


The depth of a window is its number of bits per pixel. The call passes 
a display information routine to indicate that the client wants the 
parent window depth to be identical to the display depth. 


The window class can be either input only or input-output, specified by 
the following constants: 


¢ x$c_input_only 
¢ x$c_input_output 


If the window is the same class as the parent, pass the constant 
x$c_copy_from_parent. 


Note that the only attributes clients can define for input-only windows 
are window gravity, event mask, do-not-propagate mask, override 
redirect, and cursor. 


The border width of input-only windows must be zero. 
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The visual type indicates how the window displays color values. For 
more information about visual types, see Chapter 5. 





3.3 Destroying Windows 


When a client no longer needs a window, the client should destroy it using 
either the DESTROY WINDOW or the DESTROY SUBWINDOWS routine. 
DESTROY WINDOW destroys a specified window and all its subwindows. 
DESTROY SUBWINDOWS destroys all subwindows of a specified window 
in bottom to top stacking order. 


Destroying a window frees all storage allocated for that window. If the 
window is mapped to the screen, the server notifies applications using the 
window that it has been destroyed. 





3.4 Mapping and Unmapping Windows 
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After creating a window, the client can map it to a screen using the MAP 
WINDOW or MAP SUBWINDOWS routine. Mapping generally makes a 
window visible at the location the client specified when creating it. Part or 
all of the window is not visible when the following conditions occur: 


¢ One or more windows higher in the stacking order obscures it 
¢ One or more window ancestors is not mapped 


e The new window extends beyond the boundary of its parent 


MAP WINDOW maps a window. If the window is an inferior, and one 
or more of its ancestors has not been mapped, the server considers the 
window to be mapped after the call, even though the window is not visible 
on the screen. The window becomes visible when its ancestors are mapped. 


To map all subwindows of a specified window in top to bottom order, use 
MAP SUBWINDOWS. Using the MAP SUBWINDOWS routine to map 
several windows may be more efficient than calling the MAP WINDOW 
routine to map each window. The MAP SUBWINDOWS routine enables 
the server to map all of the windows at one time instead of mapping a 
single window with the MAP WINDOW routine. 


To ensure that the window is completely visible, use the MAP RAISED 
routine, MAP RAISED reorders the stack with the window on top and 
then maps the window. Example 3-3 illustrates how a window is mapped 
and raised to the top of the stack. 
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Example 3-3 Mapping and Raising Windows 


INTEGER*4 WINDOW ! window id 
INTEGER*4 SUBWINDOW_1 ! window id 
INTEGER*4 SUBWINDOW_2 ! window id 
Cc Create windows in the following order: 
Cc WINDOW, SUBWINDOW_2, SUBWINDOW_1 
Cc 
CALL XSMAP_WINDOW(DPY, WINDOW) 
1] CALL X$MAP_WINDOW(DPY, SUBWINDOW_1) 
@ CALL X$MAP_RAISED(DPY, SUBWINDOW_2) 


@ In this example, the client creates SUBWINDOW_1 after 
SUBWINDOW_2, putting SUBWINDOW_1 at the top of the stack. 


Consequently, whether SUBWINDOW_2 were mapped before or after 
SUBWINDOW_1, SUBWINDOW_1 would obscure SUBWINDOW_2. 


The effect is illustrated in Figure 3-6. 


@® Mapping and raising SUBWINDOW_2 moves it to the top of the stack. 
It is now visible, as Figure 3—7 illustrates. 


When the client no longer needs a window mapped to the screen, call 
UNMAP WINDOW. If the window is a parent, its children are no longer 
visible after the call, although they are still mapped. The children become 
visible when the parent is mapped again. 


To unmap all subwindows of a specified window, use UNMAP 
SUBWINDOWS. UNMAP SUBWINDOWS results in an UNMAP 
WINDOW call on all subwindows of the parent, from bottom to top 
stacking order. 


3.5 Associating Properties with Windows 


Xlib enables clients to associate data with a window. This data is 
considered a property of the window. For example, a client could store 
text as a window property. Although a property must be data of only one 
type, it can be stored in 8-bit, 16-bit, and 32-bit formats. 


Xlib uses atoms to name properties. An atom is a string paired with an 
identifier. For example, a client could use the atom X$C_XA_WM_ICON_ 
NAME to name a window icon stored for later use. The atom X$C_XA_ 
WM_ICON_NAME pairs the string X$C_XA_WM_ICON_NAME with a 
value, 25, that uniquely identifies the stored name. 
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Figure 3-6 Window Before Restacking 
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In SYS$LIBRARY:DECW$XLIBDEF.H, VMS DECwindows includes 
predefined atoms such as X$C_XA_WM_ICON_NAME for commonly 

used properties. Table 3—4 lists all predefined atoms except those used to 
identify font properties and those used to communicate with the window 
manager. See Table 3-6 for a list of atoms related to window management. 
See Chapter 8 for a list of atoms related to fonts. 
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Figure 3-7 Restacked Window 
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Table 3-4 Predefined Atoms 
For Global Selection 


X$C_XA_PRIMARY 


For Cut Buffers 


X$C_XA_CUT_BUFFERO 
X$C_XA_CUT_BUFFER2 
X$C_XA_CUT_BUFFER4 
X$C_XA_CUT_BUFFER6 


For Color Maps 


X$C_XA_RGB_COLOR_MAP 
X$C_XA_RGB_BLUE_MAP 
X$C_XA_RGB_GREEN_MAP 
X$C_XA_RGB_DEFAULT_MAP 


For Resources 


X$C_XA_RESOURCE_MANAGER 
X$C_XA_ATOM 
X$C_XA_CARDINAL 
X$C_XA_CURSOR 
X$C_XA_FONT 
X$C_XA_PIXMAP 
X$C_XA_RECTANGLE 
X$C_XA_VISUALID 


X$C_XA_SECONDARY 


X$C_XA_CUT_BUFFER1 
X$C_XA_CUT_BUFFER3 
X$C_XA_CUT_BUFFER5 
X$C_XA_CUT_BUFFER7 


X$C_XA_RGB_BEST_MAP 
X$C_XA_RGB_RED_MAP 
X$C_XA_RGB_GRAY_MAP 


X$C_XA_ARC 
X$C_XA_BITMAP 
X$C_XA_COLORMAP 
X$C_XA_DRAWABLE 
X$C_XA_INTEGER 
X$C_XA_POINT 
X$C_XA_STRING 
X$C_XA_WINDOW 


In addition to providing predefined atoms, Xlib enables clients to create 
their own atom names. To create an atom name, use the INTERN ATOM 


routine, as in the following example: 


INTEGER*4 ATOM_ID 
INTEGER*4 IF EXISTS 
CHARACTER*7 ATOM NAME 
DATA ATOM NAME /’MY_ ATOM’ / 


ATOM_ID = X$INTERN_ATOM(DPY, ATOM_NAME, IF_EXISTS) 
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The routine returns an identifier associated with the string MY_ATOM. 
Xlib also returns the value of false to IF_EXISTS if the atom does not 
exist in the atom table. 


To get the name of an atom, use the GET ATOM NAME routine, as in the 
following example: 


. 


CHARACTER*100 ATOM NAME 
INTEGER*4 ATOM ID, STATUS 


ATOM_ID = 19 
STATUS = X$GET_ATOM NAME (DPY, ATOM ID, ATOM NAME) 


. 


The routine returns a string associated with the atom identifier, 39. 


Xlib enables clients to change, obtain, update, and interchange properties. 
Example 3—4 illustrates exchanging properties between two subwindows. 

The example uses the CHANGE PROPERTY routine to set a property on 
the parent window and the GET PROPERTY routine to get the data from 
the parent window. 


Example 3-4 Exchanging Window Properties 


aaa 


CHARACTER*50 PROPERTY DATA ‘Data stored as a property 
CHARACTER*50 PROP Data stored as a property 
CHARACTER*1000 PROPERTY _RETURNED 'Property returned 


RECORD /XSVISUAL/ VISUAL ! visual type 

RECORD /X$SET WIN_ATTRIBUTES/ XSWDA ! window attributes 
RECORD /X$GC_VALUES/ XGCVL ! ge values 
! 
f 


RECORD /X$SIZE HINTS/ XSZHN hints 

RECORD /XSEVENT/ EVENT input event 

PARAMETER WIN WIDTH = 600, WIN_HEIGHT = 600, 
SUB_WIDTH = 300, SUB HEIGHT = 150, 


WIN_X = 100, WIN_Y = 100, 
SUB1_X = 150, SUB1_Y = 100, 
SUB2_X = 150, SUB2_Y = 350, 
OFFSET = 0, LENGTH = 1000 


DATA PROPERTY_DATA /’You clicked MB1’/ 


PRE eR 


Create the WINDOW window 


DEPTH = XSDEFAULT_DEPTH_OF_ SCREEN (SCREEN) 
CALL X$DEFAULT VISUAL _OF_ SCREEN (SCREEN, VISUAL) 
ATTR MASK = X$M_CW_EVENT MASK .OR. X$M_CW_BACK_PIXEL 


XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON PRESS 
ad .OR. X$M_PROPERTY_CHANGE 
XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 

1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 1) 





(continued on next page) 
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Example 3—4 (Cont.) Exchanging Window Properties 





WINDOW = XS$CREATE WINDOW (DPY, 

ab XSROOT_WINDOW_OF_SCREEN (SCREEN) , 

1 WIN_X, WIN_Y, WIN_WIDTH, WIN_HEIGHT, 0, 

1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Cc 
Cc Create the subwindows 
Cc 
XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 2) 
SUBWINDOWL = XSCREATE WINDOW (DPY, WINDOW, 
1 SUB1_X, SUB1_Y, SUB_WIDTH, SUB_HEIGHT, 4, 
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
SUBWINDOW2 = XSCREATE WINDOW (DPY, WINDOW, 
1 SUB2_X, SUB2_Y, SUB_WIDTH, SUB_HEIGHT, 4, 
1, DEPTH, X$C_INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 
Cc 
Cc Handle events 
Cc 
DO WHILE (.TRUE.) 
CALL XSNEXT_EVENT (DPY, EVENT) 
IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE - AND. 
i EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW) THEN 
CALL XS$DRAW_IMAGE_ STRING (DPY, WINDOW, GC, 
1 150, 25, ‘Press MB1 in the upper window.’) 
CALL XSDRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 50, ’To exit, press MB2.’) 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON PRESS -AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON -EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT(%VAL(1)) 
END IF 
IF (EVENT.EVNT_BUTTON.X$L_BTEV_WINDOW .EQ. SUBWINDOW1 .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON -HQ. X$C_BUTTON1) THEN 
Oo CALL X$CHANGE_PROPERTY (DPY, WINDOW, X$C_XA_CUT_BUFFERO, 
1 X$C_XA STRING, 16, X$C_PROP_MODE REPLACE, 
1. SREF (PROPERTY_DATA), 15) 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_PROPERTY_NOTIFY . AND. 
1 EVENT.EVNT_PROPERTY.X$L_PPEV_ATOM .EQ. X$C_XA_CUT_BUFFERO) THEN 
e CALL X$GET_WINDOW_PROPERTY (DPY, WINDOW, X$C_XA_CUT_BUFFERO, 
1 OFFSET, LENGTH, TRUE, X$C_XA_STRING, TYPE_RETURNED, 
1 FORMAT RETURNED, NUM_ITEMS RETURNED, BYTES_REMAINING, 
1 , SREF (1000) , REF (PROPERTY_RETURNED) ) 





(continued on next page) 
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Example 3-4 (Cont.) Exchanging Window Properties 


3) 


END 
END 


CALL X$DRAW STRING(DPY, SUBWINDOW2, GC, 75, 75, 
PROPERTY RETURNED, NUM_ITEMS RETURNED) 


END IF 
DO 


cS) 


When the user clicks MB1 in subwindow SUBWINDOW/1, the client 
calls the CHANGE PROPERTY routine. CHANGE PROPERTY causes 
the server to change the property identified by the atom X$C_XA_ 
CUT_BUFFER0O to the value specified by PROPERTY_DATA. The 
property is associated with the parent window, WINDOW. 


When changing properties, the client can specify how the server 
should treat them. If the client specifies the constant x$c_prop_ 
mode_replace, the server discards the previous property. If the client 
specifies the constant x$c_prop_mode_prepend, the server inserts 
the new data at the beginning of the existing property data. If the 
client specifies the constant x$c_prop_mode_append, the server 
inserts the new data at the end of the existing property data. 


Changing the property causes the server to send a property notify 
event to the parent window, WINDOW. For information about event 
handling, see Chapter 9. 


After checking to ensure that the changed property is the one to 
obtain, the client calls the GET WINDOW PROPERTY routine. Note 
that the client returns the property, which is a string type, into a 
buffer of 1000 bytes, specified by the variable 
PROPERTY_RETURNED. 


After getting the string data from the parent window, the client uses 
it to write text in SUBWINDOW2. For information about writing text, 
see Chapter 8. 


In addition to the GET WINDOW PROPERTY routine, Xlib includes the 
property-management routines described in Table 3-5. 


Table 3-5 Routines for Managing Properties 


Routine Description 

LIST PROPERTIES Reiurns a list of properties defined for a specified 
window. 

ROTATE WINDOW Rotates the properties of a specified window and 

PROPERTIES generates a property notify event. For more information 


about property notify events, see Chapter 9. 


DELETE PROPERTY Deletes a specified property. 
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3.5.1 Using Properties to Communicate with the Window Manager 


Xlib provides predefined atoms to enable clients to communicate hints to 
the window manager about the following: 


¢ Window names 

¢ Icon names 

e Pixmaps used to define window icons 

¢ Commands used to start the application 

¢ Position and size of windows in their startup state 
¢ Initial state of windows 

¢ Input that windows accept 


* Names used to retrieve application resources 


Table 3-6 describes the atom names, data types, and formats of these 
properties. 


Table 3-6 Atom Names of Window Manager Properties 


Atom Data Type Format Description of the Property 
X$C_XA_WM_NAME STRING 8 Application name 
X$C_XA_WM_ICON_NAME STRING 8 Icon name 
X$C_XA_WM_NORMAL_HINTS WM_SIZE_HINTS 32 Size hints for a window in its 
normal state 
X$C_XA_WM_ZOOM_HINTS WM_SIZE_HINTS 32 Size hints for a zoomed window 
X$C_XA_WM_HINTS WM_HINTS 32 Hints about keyboard input, 


initial state, icon pixmap, icon 
window, icon position, and icon 
mask 
X$C_XA_WM_COMMAND STRING 8 Command used to start the 
client 
X$C_XA_WM_ICON_SIZE WM_ICON_SIZE 32 Specifies the icon size 
supported by the window 
manager 
X$C_XA_WM_CLASS STRING 32 Allows window manager to 
obtain the application resources 
from the resource database 
X$C_XA_WM_TRANSIENT_FOR WINDOW 32 Indicates that a window, such 
as a dialog box, is transient 


Xlib provides the following methods for using the properties described in 
Table 3—6 to communicate with the window manager: 


¢ Defining properties with the SET WM HINTS routine—SET WM 
HINTS uses the WM hints data structure to define hints about 
keyboard input, initial state of the window, icon pixmap, icon window, 
icon position, icon mask, and window group. 
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¢ Using convenience routines to communicate with the window 
manager—Xlib includes routines that enable clients to communicate 
individual hints about window names, window icon names, and 
window classes. 


¢ Providing and obtaining hints about the size and position of windows— 
Xlib routines communicate information about the size and position of 
windows. 


e Changing the values of a property—Xlib includes a routine to change 
the value of an existing property. 


Note that it is not guaranteed that the window manager will apply window 
manager hints. 


This section describes how to use properties to communicate with the 
window manager. 


3.5.1.1 Defining Properties Using the SET WM HINTS Routine 
Use the SET WM HINTS routine to provide the window manager with 
hints about keyboard input, initial window state, icon pixmap, icon 
window, icon position, icon mask, and window group. A window manager 
can use the window group property to treat a set of windows as a group. 
For example, if a client manipulates multiple children of the root window, 
SET WM HINTS enables the client to provide enough information so that 
a window manager can make all windows into icons, rather than just one 
window. 


Xlib provides a WM hints data structure to enable clients to specify these 
hints easily. Figure 3-8 illustrates the wm hints data structure. Table 3-7 
describes its members. 


Figure 3-8 WM Hints Data Structure 
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Table 3-7 WM Hints Data Structure Members 


Member Name 


X$L_HINT_FLAGS 
X$L_HINT_INPUT 


X$L_HINT_INITIAL_STATE 


X$L_HINT_ICON_PIXMAP 


Contents 


Specifies the members of the data structure that are defined. 


Indicates whether or not the client relies on the window manager to get 
keyboard input. 


Defines how the window should appear in its initial configuration. Possible 
initial states are as follows: 


Constant Description 

x$c_dont_care_state Client is not interested in the initial state 
x$c_normal_state Initial state used most often 
x$c_zoom_state Window starts zoomed 

x$c_iconic_state Window starts as an icon 
x$c_inactive_state Window is seldom used 


Identifies the pixmap used to create the window icon. 


X$L_HINT_ICON_WINDOW Specifies the window to be used as an icon. 


X$L_HINT_ICON_X 
X$L_HINT_ICON_Y 
X$L_HINT_ICON_MASK 


Specifies the initial x-coordinate of the icon position. 
Specifies the initial y-coordinate of the icon position. 
Specifies the pixels of the icon pixmap used to create the icon. 


X$L_HINT_WINDOW_GROUP Specifies that a window belongs to a group of other windows. 


3.5.1.2 
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Defining Individual Properties 

Xlib includes routines to enable clients to define individual properties 
for communicating with the window manager about window names, icon 
names, and window classes. 


To define a window name, use the STORE NAME routine. The sample 
program in Chapter 1 uses the STORE NAME routine to define the name 
of its parent window, as follows: 

CALL X$STORE_NAME(DPY, WINDOW 1, 

1 ‘A Sample Xlib Program’ ) 
To get the name of a window, use the FETCH NAME routine. The routine 


either returns the name of the specified window or sets the value of the 
X$C_XA_WM_NAME property to null. 


The SET ICON NAME and GET ICON NAME routines define and get the 


name of a window icon. 
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To define and get the class of a specified window, use the SET CLASS 
HINT and GET CLASS HINT routines. The routines refer to the class 
hint data structure illustrated in Figure 3-9. 


Figure 3-9 Class Hint Data Structure 





x$a_chnt_res_class 4 


Table 3—8 describes members of the data structure. 


Table 3-8 Class Hint Data Structure Members 


Member Name 


X$A_CHNT_RES_NAME 


X$A_CHNT_RES_CLASS 


3.5.1.3 


Contents 


Defines the name of the window. The name defined in this data structure may 
differ from the name defined by the X$C_XA_WM_NAME property. The 
X$C_XA_WM_NAME property specifies what should be displayed in the title bar. 
Consequently, it may contain a temporary name, as in the name of a file a client 
currently has in a buffer. In contrast to X$C_XA_WM_NAME, this member defines 
the formal window name that clients should use when retrieving resources from 
the resource database. 


Defines the class of the window. 


At times, clients may need to indicate to the window manager that a 
top-level window is really only a transient window. For instance, a client 
may communicate to the window manager that the window is a dialog box 
mapped on behalf of another window. To communciate this, a client calls 
the SET TRANSIENT FOR HINT routine. The routine sets the 
X$C_XA_WM_TRANSIENT_FOR property of the transient window and 
associates the transient window with a main window. To obtain the 
X$C_XA_WM_TRANSIENT_FOR property for a specified window, call the 
GET TRANSIENT FOR HINT routine. 


To define the command that invokes an application in a specified window, 
use the SET COMMAND routine. 


Providing Size Hints 

Xlib provides routines to communicate with the window manager about the 
size and position of windows in their normal and zoomed startup states. 
Use the following method to specify the size and position of a window in 
its usual startup state: 


1. Assign values to the relevant members of the size hints data structure, 
including the X$L_SZHN_FLAGS member. This member specifies 
which members of the data structure are defined. Table 3—9 lists the 
flags. 
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2 Call the SET NORMAL HINTS routine 


Table 3-9 Set Window Attributes Data Structure Flags 


Flag Name Size Hints Member 

x$m_p_position User-specified position of the window 

x$m_us_size User-specified size of the window 

x$m_p_position Client-specified position 

x$m_p_size Client-specified size 

x$m_p_min_size Client-specified minimum size of the window 
x$m_p_max_size Client-specified maximum size of the window 
x$m_p_resize_inc Client-specified increments for resizing the window 
x$m_p_aspect Client-specified minimum and maximum aspect ratios 
x$m_p_all_hints The bitwise OR of the following flags: x$m_p_position, 


x$m_p_size, x$m_p_min_size, x$m_p_max_size, 
x$m_p_resize_inc, and x$m_p_aspect. 


Figure 3~10 illustrates the size hints data structure. Table 3-10 describes 
its contents. 


Figure 3-10 Size Hints Data Structure 
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Figure 3-10 (Cont.) Size Hints Data Structure 









: 
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Table 3-10 Size Hints Data Structure Members 

Member Name Contents 

X$L_SZHN_FLAGS Defines which members the client is assigning values to. 

X$L_SZHN_X Specifies the x-coordinate that defines window position. 

X$L_SZHN_Y Specifies the y-coordinate that defines window position. 

X$L_SZHN_WIDTH Defines the width of the window. 

X$L_SZHN_HEIGHT Defines the height of the window. 

X$L_SZHN_MIN_WIDTH Specifies the minimum useful width of the window. 

X$L_SZHN_MIN_HEIGHT Specifies the minimum useful height of the window. 

X$L_SZHN_MAX_WIDTH Specifies the maximum useful width of the window. 

X$L_SZHN_MAX_HEIGHT Specifies the maximum useful height of the window. 

X$L_SZHN_WIDTH_INC Defines the increments by which the width of the window can be resized. 

X$L_SZHN_HEIGHT_INC Defines the increments by which the height of the window can be resized. 

X$L_SZHN_MNAS_X With the X$L_SZHN_MNAS_Y member, specifies the minimum aspect ratio of the 
window. 

X$L_SZHN_MNAS_Y With the X$L_SZHN_MNAS_X member, specifies the minimum aspect ratio of the 
window. 

X$L_SZHN_MXAS_X With the X$L_SZHN_MXAS_Y member, specifies the maximum aspect ratio of the 
window. 

X$L_SZHN_MXAS_Y With the X$L_SZHN_MXAS_X member, specifies the maximum aspect ratio of the 
window. 


Setting the minimum and maximum aspects indicates the preferred range of the 
size of a window. An aspect is expressed in terms of a ratio between x and y. 

For example, if the minimum aspect of x is 1 and y is 2, and the maximum aspect of 
x is 2 and y is 5, then the minimum window size is a ratio of 1/2, and the maximum 
is a ratio of 2/5. In this case, a window could have a width of 300 pixels and a 
height of 600 pixels minimally, and maximally a width of 600 pixels and a height of 
1500 pixels. 


The following illustrates using the size hints data structure to set the 
normal window manager hints for a window: 
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XSZHN.X$L_SZHN_X = 362 

XSZHN.X$L_SZHN_Y = 282 

XSZHN.X$L_SZHN WIDTH = 400 

XSZHN.X$L_SZHN HEIGHT = 300 

XSZHN.X$L_SZHN FLAGS = X$C_P_POSITION .OR. X$C_P_SIZE 


CALL X$SET_NORMAL _HINTS(DPY, WINDOW_1, XSZHN) 


The example sets hints about the size and location of WINDOW_1. 


3.5.2 Exchanging Properties Between Clients 
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Xlib provides routines that enable clients to exchange properties. The 
properties, which are global to the server, are called selections. Text cut 
from one window and pasted into another window exemplifies the global 
exchange of properties. The text cut in window A is a property owned by 
client A. Ownership of the property transfers to client B, who then pastes 
the text into window B. 


Properties are exchanged between clients by a series of calls to routines 
that manage the selected text. When a user drags the pointer cursor, 
client A responds by calling the SET SELECTION OWNER routine. SET 
SELECTION OWNER identifies client A as the owner of the selected text. 
The routine also identifies the window of the selection, associates an atom 
with the text, and puts a timestamp on the selection. The atom, 
X$C_XA_PRIMARY, names the selection. The timestamp enables any 
clients competing for the selection to determine selection ownership. 


Clients can determine the owner of a selection by calling the GET 
SELECTION OWNER routine. 


When a user decides to paste the selected text in window B, client B, who 
owns window B, sends client A a selection request. The request identifies 
the window requesting the cut text and the format in which the client 
would like the property transferred. 


In response to the request, client A first checks to ensure that the time of 
the request corresponds to the time in which client A owns the selection. 
If the time coincides, and if the selection is in the data type required by 
client B, client A notifies client B that the text is stored and available. The 
text is then moved to client B. 


After receiving the text, client B informs client A that client B is the 
current owner of the selection. 


In addition to requesting a selection in its current format, clients can 

call the CONVERT SELECTION routine. CONVERT SELECTION 

asks the owner of a selection to convert it to a particular data type. If 
conversion is possible, the client converting the selection notifies the client 
requesting the conversion that the selection is available. The property is 
then exchanged as previously described. 
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Clients request and notify other clients of selections by using events. For 
information about using events to request, convert, and notify clients of 
selections, see Chapter 9. For style guidelines about using selections, see 
the XUI Style Guide. 


Changing Window Characteristics 


Xlib provides routines that enable clients to change window position, size, 
border width, stacking order, and attributes. 


This section describes how to use Xlib routines to do the following: 
e Change multiple window characteristics in one call 

¢ Change position, size, or border width 

¢ Change stacking order 


¢ Change window attributes 


Reconfiguring Windows 


Xlib enables clients either to change window characteristics using. one 
call or to use individual routines to reposition, resize, or to change border 
width. 


The CONFIGURE WINDOW routine enables clients to change window 
position, size, border width, and place in the hierarchy. To change these 
window characteristics in one call, use the CONFIGURE WINDOW 
routine, as follows: 


1 Set values of relevant members of a window changes data structure. 
2 Indicate what is to be reconfigured by specifying the appropriate flag 
in the CONFIGURE WINDOW value_mask argument. 


The window changes data structure enables clients to specify one or more 
values for reconfiguring a window. Figure 3-11 illustrates the window 
changes data structure. Table 3-11 describes the members of the data 
structure. 


Figure 3-11 Window Changes Data Structure 
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Figure 3-11 (Cont.) Window Changes Data Structure 
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Table 3-11 Window Changes Data Siructure Members 


Member Name Contents 


X$L_WCHG_X Defines the x-coordinate of the new location of the window relative to the 
origin of its parent. The x- and y-coordinates specify the upper left outside 
corner of the window. 


X$L_WCHG_Y: Defines the y-coordinate of the new location of the window relative to the 
origin of its parent. The x- and y-coordinates specify the upper left outside 
corner of the window. 


X$L_WCHG_WIDTH Defines the new width of the window, excluding the border. 
X$L_WCHG_HEIGHT Defines the new height of the window, excluding the border. 
X$L_WCHG_BORDER_WIDTH Specifies the new window border in pixels. 

X$L_WCHG_SIBLING Specifies the sibling window for stacking order. 
X$L_WCHG_STACK_MODE Defines how the window is restacked. Table 3-12 lists constants and 


definitions for restacking windows. 





The client can change the hierarchical position of a window in relation to 
all windows in the stack or to a specified sibling. If the client changes the 
size, position, and stacking order of the window by calling CONFIGURE 
WINDOW, the server restacks the window based on its final, not initial, 
size and position. Table 3-12 lists constants and definitions for restacking 
windows. 


Table 3-12 Stacking Values 





Constants Relative to All Relative to Sibling 

x$c_above Top of stack. Just above sibling. 

x$c_below Bottom of stack. Just below sibling. 

x$c_top_if lf any sibling obscures a window, the server __ If the specified sibling obscures a window, the 
places the obscured window on top of the server places the obscured window at the top of 
stack. the stack. 


x$c_bottom_if If a window obscures any sibling, the server __If the window obscures the specified sibling, the 
places the obscuring window at the bottom server places the obscuring window at the bottom 


of the stack. of the stack. 

x$c_opposite If any sibling obscures a window, the server If the specified sibling obscures a window, the 
places the obscured window on top of the server places the obscuring window on top of the 
stack. If a window obscures any window, stack. If a window obscures the specified sibling, 
the server places the obscuring window at the server places the obscuring window on the 
the bottom of the stack. bottom of the stack. 
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Xlib assigns a symbol to the flag associated with each member of the data 
structure (Table 3-13). 


Table 3-13 Window Changes Data Structure Flags 


Flag Name Window Changes Member 
x$m_cw_x X$L_WCHG_X 

x$m_cw_y X$L_WCHG_Y 

x$m_cw_width X$L_WCHG_WIDTH 
x$m_cw_height X$L_WCHG_HEIGHT 
x$m_cw_border_width X$L_WCHG_BORDER_WIDTH 
x$m_cw_sibling X$L_WCHG_SIBLING 


x$m_cw_stack_mode X$L_WCHG_STACK_MODE 


Example 3-5 illustrates using CONFIGURE WINDOW to change the 
position, size, and stacking order of a window when the user presses a 
button. 


Example 3-5 Reconfiguring a Window 


Cc 
Cc 
C 





This program changes the position, size, and stacking 
order of SUBWINDOW_1 


RECORD /X$WINDOW_CHANGES/ XWC 


WCHG_MASK = X$M CW_X .OR. X$M_CW_Y .OR. X$M_CW_WIDTH .OR. 


1 X$M_CW_HEIGHT .OR. X$M_CW SIBLING .OR. XSM_CW_STACK_MODE 


XWC.X$L_WCHG X = 200 

XWC.X$L_WCHG_Y = 350 

XWC.X$L_WCHG WIDTH = 200 
XWC.XSL_WCHG HEIGHT = 50 
XWC.X$L_WCHG SIBLING = SUBWINDOW 2 
XWC.X$L_WCHG STACK MODE = X$C_ABOVE 


CALL X$CONFIGURE_WINDOW(DPY, SUBWINDOW_1, WCHG_MASK, XWC) 


@ Specify the members of the window changes data structure that 
have assigned values. Create a mask by performing a bitwise OR 
operation on relevant flags that indicate which members of WINDOW 
CHANGES the client will define. 


® Assign values to relevant members of the window 
changes data structure. Because the client identifies a sibling 
(SUBWINDOW_1), it must also choose a mode for stacking operations. 


© The call to reconfigure SUBWINDOW_1. The CONFIGURE WINDOW 
routine call has the following format: 


X$CONFIGURE_WINDOW(display, window_id, change _mask, values) 
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Figure 3—12 illustrates how the windows look after being reconfigured. 
Figure 3-12 Reconfigured Window 


SUBWINDOW_1 SUBWINDOW_2 
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Table 3-14 lists routines to change individual window characteristics. 


Table 3-14 Window Configuration Routines 


Routine Description 

MOVE WINDOW Moves a window without changing its size. 

RESIZE WINDOW Changes the size of a window without moving it. The 
upper left window coordinate does not change after 
resizing. 

MOVE RESIZE WINDOW Moves and changes the size of a window. 

SET WINDOW BORDER Changes the border width of a window. 

WIDTH 


3.6.2 Effects of Reconfiguring Windows 


It is important to know how reconfiguring windows affects graphics and 
text drawn in them by the client. (See Chapter 6 for a description of 
working with graphics and Chapter 8 for a description of writing text.) 
When a client resizes a window, window contents are either moved or lost, 
depending on the bit gravity of the window. Bit gravity indicates that a 
designated region of the window should be relocated when the window is 
resized. Resizing also causes the server to resize children of the changed 
window. 


To control how the server moves children when a parent is resized, set the 
window gravity attribute. Table 3-15 lists choices for retaining window 
contents and controlling how the server relocates children. 


Table 3-15 Gravity Definitions 


Movement of Window Contents and 
Constant Name Subwindows 


x$c_forget_gravity The server always discards window contents and 
tiles the window with its selected background. If 
the client has not specified a background, existing 
screen contents remain the same. 


x$c_north_west_gravity Not moved. 

x$c_north_gravity Moved to the right half the window width. 

x$c_north_east_gravity Moved to the right the distance of the window 
width. 

x$c_west_gravity Moved down half the window height. 

x$c_center_gravity Moved to the right half the window width and down 
half the window height. 

x$c_east_gravity Moved to the right the distance of the window width 


and down half the window height. 
x$c_south_west_gravity Moved down the distance of the window height. 


(continued on next page) 
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Table 3-15 (Cont.) Gravity Definitions 


Movement of Window Contents and 


Constant Name Subwindows 

x$c_south_gravity Moved to the right half the window width and down 
the distance of the window height. 

x$c_south_east_gravity Moved to the right the distance of the window width 
and down the distance of the window height. 

x$c_static_gravity Contents or origin is not moved relative to the 


origin of the root window. Static gravity only takes 
effect with a change in window width or height. 


x$c_unmap_gravity Window should not be moved; the child should be 
unmapped when the parent is resized. 


Figure 3-13 illustrates how the server moves the contents of a 
reconfigured window when the bit gravity is set to the constant 
x$c_east_gravity. 


Figure 3-13 East Bit Gravity 
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Figure 3-14 illustrates how the server moves a child window if its parent 
is resized and its window gravity is set to the constant x$c_northwest_ 
gravity. 
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Figure 3-14 Northwest Window Gravity 
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3.6.3. Changing Stacking Order 


Xlib provides routines that alter the window stacking order in the 
following ways: 


e A specified window moves to either the top or the bottom of the stack. 
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¢ The lowest mapped child obscured by a sibling moves to the top of the 
stack. 


¢ The highest mapped child that obscures a sibling moves to the bottom 
of the stack. 


Use the RAISE WINDOW and LOWER WINDOW routines to move a 
specified window to either the top or the bottom of the stack, respectively. 


To raise the lowest mapped child of an obscured window to the top of the 
stack, call CIRCULATE SUBWINDOWS UP. To lower the highest mapped 
child that obscures another child, call CIRCULATE SUBWINDOWS 
DOWN. The CIRCULATE SUBWINDOWS routine enables the client to 
perform these operations by specifying either the constant x$c_raise_ 
lowest or the constant x$c_lower_highest. 


To change the order of the window stack, use RESTACK WINDOW, which 
changes the window stack to a specified order. Reordered windows must 
have a common parent. If the first window the client specifies has other 
unspecified siblings, its order relative to those siblings remains unchanged. 


Changing Window Attributes 
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Xlib provides routines that enable clients to change the following: 
¢ Default contents of an input-output window 

¢ Border of an input-output window 

¢ Treatment of the window when it or its relative is obscured 

¢ Treatment of the window when it or its relative is moved 


* Information the window receives about operations associated with 
other windows 


¢ Color 


¢ Cursor 


Section 3.2.2 includes descriptions of window attributes and their 
relationship to the set window attributes data structure. 


This section describes how to change any attribute using the CHANGE 
WINDOW ATTRIBUTES routine. In addition to CHANGE WINDOW 
ATTRIBUTES, Xlib includes routines that enable clients to change 
background and border attributes. Table 3—16 lists these routines and 
their functions. 
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Table 3-16 Routines for Changing Window Attributes 


Routine Description 

SET WINDOW BACKGROUND Sets the background pixel 

SET WINDOW BACKGROUND PIXMAP Sets the background pixmap 

SET WINDOW BORDER Sets the window border to a specified 
pixel 

SET WINDOW BORDER PIXMAP Sets the window border to a specified 
pixmap 


To change any window attribute, use CHANGE WINDOW ATTRIBUTES 
as follows: 


e Assign a value to the relevant member of a set window attributes data 
structure. 


¢ Indicate the attribute to change by specifying the appropriate flag 
and passing it to the CHANGE WINDOW ATTRIBUTES value_mask 
argument. To define more than one attribute, indicate the attributes 
by doing a bitwise OR on the appropriate flags. 


See Table 3-3 for symbols Xlib assigns to each member to facilitate 
referring to the attributes. 


Example 3-6 illustrates using CHANGE WINDOW ATTRIBUTES to 
redefine the characteristics of a window. 


Example 3-6 Changing Window Attributes 


RECORD /XSSET_WIN_ATTRIBUTES/ XSWDA 


ATTR_MASK = X$M_CW_BORDER_PIXEL .OR. X$M_CW_BACK PIXEL 


XSWDA.X$L_SWDA_BACKGROUND_PIXEL = X$BLACK_PIXEL OF_SCREEN (SCREEN) 
XSWDA.X$L_SWDA_BORDER_PIXEL = X$WHITE PIXEL OF SCREEN (SCREEN) 


CALL X$CHANGE WINDOW_ATTRIBUTES (DPY, WINDOW, ATTR_MASK, XSWA) 


@ Assign new values to a set window attributes data structure. 


@ Call CHANGE WINDOW ATTRIBUTES to change the window 
attributes. The CHANGE WINDOWS attributes routine has the 
following format: 


XS$CHANGE_ WINDOW ATTRIBUTES (display, window_id, 
attributes_mask, attributes) 


Specify the attributes to change with a bitwise inclusive OR of the 
relevant symbols listed in Table 3-3. The values argument passes the 
address of a set window attributes data structure. 
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3.7 Getting Information About Windows 


Table 3-17 lists changes in attributes and their effects. 


Table 3-17 Effects of Window Attribute Changes 


Attribute Changed 


Effects 





Background 


Border 


Bit and window gravity 
Backing store 

Backing planes 
Backing pixels 

Save under 


Event mask 

Do not propagate mask 
Color map 

Cursor 


Window contents are unchanged. 


If the window is a root window, specifying the constant 
x$c_none or x$c_parent_relative restores the default 
background pixmap. 


The server does not repaint the background 
automatically. 


Setting the border causes the border to be repainted. 


If a background change causes a change in the 
border tile origin, the server repaints the border. 


Specifying the constant x$c_copy_from_parent on a 
root window restores the default border pixmap. 


A change in window gravity has no effect until the 
window is resized. 


In this release of the DECwindows server, backing 
store is not supported. 


in this release of the DECwindows server, backing 
planes is not supported. 


In this release of the DECwindows server, backing 
pixels is not supported. 


If the window is mapped, changing the value of save 
under may have no immediate effect. 


See Chapter 9. 
See Chapter 9. 
See Chapter 5. 


Specifying the constant x$c_none on a root window 
restores the default cursor. 


Using Xlib information routines, clients can get information about the 
parent, children, and number of children in a window tree; window 
geometry; the root window in which the pointer is currently visible; and 


window attributes. 


Table 3-18 lists and describes Xlib routines that return information about 


windows. 
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Table 3-18 Window Information Routines 








Routine Description 
QUERY TREE Returns information about the window tree 
GET GEOMETRY Returns information about the root window 


identifier, coordinates, width and height, border 
width, and depth 


QUERY POINTER Returns the root window the pointer is 
currently on and the pointer coordinates 
relative to the root window origin 


GET WINDOW ATTRIBUTES Returns information from the window attributes 
data structure 





To get information about window attributes, use the GET WINDOW 
ATTRIBUTES routine. The client receives requested information in the 
window attributes data structure. Figure 3-15 illustrates the window 
attributes data structure. Table 3-19 describes the members of the data 
structure. 


Figure 3-15 Window Attributes Data Structure 
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Figure 3-15 (Cont.) Window Attributes Data Structure 
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Table 3-19 Window Attributes Data Structure Members 


Member Name 


Contents 





X$L_WDAT_X 
X$L_WDAT_Y 
X$L_WDAT_WIDTH 
X$L_WDAT_HEIGHT 


X$L_WDAT_BORDER_WIDTH 
X$L_WDAT_DEPTH 
X$L_WDAT_VISUAL 


X$L_WDAT_ROOT 
X$L_WDAT_CLASS 


X$L_WDAT_BIT_GRAVITY 
X$L_WDAT_WIN_GRAVITY 


X$L_WDAT_BACKING_STORE 
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Specifies the x-coordinate of the upper left corner of the window 
relative to its parent. 


Specifies the y-coordinate of the upper left corner of the window 
relative to its parent. 


Specifies the width of the window, excluding the window border, in 
pixels. 


Specifies the height of the window, excluding the window border, in 
pixels. 


Specifies the width of the window border in pixels. 
Specifies the bits per pixel of the window. 


The visual data structure associated with the window. The visual 
data structure specifies how displays should treat color resources. 
For more information, see Section 3.5.1. 


Identifies the screen with which the window is associated. 


Specifies whether the window accepts input and output, or input 
only. 


Specifies how pixels should be moved when the window is resized. 


Specifies how the window should be repositioned when its parent is 
resized. 


Indicates whether or not the server should maintain a record 
of portions of a window that are obscured when the window is 
mapped. In this release, clients must maintain window contents. 
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Table 3-19 (Cont.) Window Attributes Data Structure Members 


Member Name 


X$L_WDAT_BACKING_PLANES 


X$L_WDAT_BACKING_PIXEL 


X$L_WDAT_SAVE_UNDER 


X$L_WDAT_COLORMAP 


X$L_WDAT_MAP_INSTALLED 


X$L_WDAT_MAP_STATE 


X$L_WDAT_ALL_EVENTS_MASK 


X$L_WDAT_YOUR_EVENT_MASK 


X$L_WDAT_DO_NOT_PROPAGATE_MASK 


X$L_WDAT_OVERRIDE_REDIRECT 


X$L_WDAT_SCREEN 


Contents 


indicates (with bits set to 1) which bit planes of the window hold 
dynamic data that must be preserved in backing stores and during 
save under operations. In this release, clients must maintain their 
own data. 


Defines what values to use in planes not specified by X$L_WDAT_ 
BACKING_PLANES. In this release, clients must maintain their own 
values. 


Setting this member to true informs the server that the client would 
like the contents of the screen saved when the window obscures 
them. Saving the contents of obscured portions of the screen is not 
guaranteed. 


Specifies the color map, if any, that best reflects the colors of the 
window. The color map must have the same visual type as the 
window. If it does not, an error occurs. For more information about 
color maps, see Chapter 5. 


If set to true, indicates that the color map is currently installed and 
the window is being displayed in its correct colors. 


Indicates whether the window is mapped and viewable. Clients can 
specify the following constants: 


Constant Name Description 
x$c_is_unmapped Indicates that the window is not mapped 
x$c_is_unviewable Indicates that the window is mapped, but 


that one of its ancestors is unmapped, 
causing the window to be unviewable 


x$c_is_viewable Indicates that the window is mapped and 
viewable 


Indicates the set of events in which all applications have an 
interest. X$L_WDAT_ALL_EVENTS_MASK is the inclusive OR of 
all event masks set for the window. For more information about 
event masks, see Chapter 9. 


Indicates the events about which the querying client is interested in 
receiving notice. 


Defines which events should not be propagated to a window’s 
ancestors when no application has the event type selected in the 
window. 


Specifies whether requests to map and configure the window 
should override a request by another client to redirect those calls 
(see Chapter 9). Typically, this mask, which informs the window 
manager not to tamper with the window, should be used only on 
subwindows such as menus. 


Specifies the screen on which the window is mapped. 





4 Defining Graphics Characteristics 


After opening a display and creating a window, clients can draw lines 
and shapes, create cursors, and draw text. Creating a graphics object is 

a two-step process. Clients first define the characteristics of the graphics 
object and then create it. For example, before creating a line, a client first 
defines line width and style. After defining the characteristics, the client 
creates the line with the specified width and style. 


This chapter describes how to define the graphics characteristics prior to 
creating them, including the following topics: 


¢ The graphics context—A description of the graphics characteristics a 
client can define and the GC values data structure used to define them 


¢ Defining graphics characteristics—How to define graphics 
characteristics using the CREATE GC routine 


* Copying, changing, and freeing atiributes—How to copy, change, and 
undefine graphics characteristics 


¢ Defining graphics characteristics efficiently—How to work efficiently 
with several sets of graphics characteristics 


Chapter 6 describes how to create graphics objects. Chapter 8 describes 
how to work with text. 


4.1 The Graphics Context 


The characteristics of a graphics object make up its graphics context. As 
with window characteristics, Xlib provides a data structure and routine 

to enable clients to define multiple graphics characteristics easily. By 
setting values in the GC values data structure and calling the CREATE 
GC routine, clients can define all characteristics relevant to a graphics 
object. 


Xlib also provides routines that enable clients to define individual or 
functional groups of graphics characteristics. 


Xlib always records the defined values in a GC data structure, which is 
reserved for the use of Xlib and the server only. This occurs when clients 
define graphic characteristics using either the CREATE GC routine or one 
of the individual routines. Table 4—1 lists the default values of the GC 
data structure. 
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Table 4-1 GC Data Structure Default Values 


Member 


Function 

Plane mask 
Foreground 
Background 

Line width 

Line style 

Cap style 

Join style 

Fill style 

Fill rule 

Arc mode 

Tile 

Stipple 

Tile or stipple x origin 
Tile or stipple y origin 
Font 

Subwindow mode 
Graphics exposures 
Clip x origin 

Clip y origin 

Clip mask 

Dash offset 

Dashes 


Default Value 


x$c_gx_copy 

All ones 

0 

1 

0 

Solid 

Butt 

Mitre 

Solid 

Even odd 

Pie slice 

Pixmap of unspecified size filled with foreground pixel 
Pixmap of unspecified size filled with ones 
0 

0 

Varies with implementation 
Clip by children 

True 

0 

0 

None 

0 

4 (the list [4,4]) 


4.2 Defining Multiple Graphics Characteristics in One Call 


Xlib enables clients to define multiple characteristics of a graphics object 
in one call. To define multiple characteristics, use the CREATE GC routine 
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as follows: 


¢ Assign values to the relevant members of the GC values data 


structure. 


* Indicate the attributes to define by specifying the appropriate flag and 
passing the flag to the value_mask argument of the routine. To define 
more than one attribute, do a bitwise OR on the appropriate attribute 


flags. 
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Figure 4—1 illustrates the GC values data structure. 
Figure 4-1 GC Values Data Structure 
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Table 4—2 describes the members of the data structure. 


Table 4-2 GC Values Data Structure Members 


Member Name 


X$L_GCVL_FUNCTION 


X$L_GCVL_PLANE_MASK 


X$L_GCVL_FOREGROUND 


Contenis 


Defines how the server computes pixel values when the client updates a 
section of the screen. The following lists available functions: 


Constant Name 


X$C_GX_CLEAR 
x$C_GX_AND 
X$C_GX_AND_REVERSE 
X$C_GX_COPY 
X$C_GX_AND_INVERTED 
X$C_GX_NOOP 
X$C_GX_XOR 
X$C_GX_OR 
X$C_GX_NOR 
X$C_GX_EQUIV 
X$C_GX_INVERT 
X$C_GX_OR_REVERSE 
X$C_GX_COPY_INVERTED 
X$C_GX_OR_INVERTED 
X$C_GX_NAND 
X$C_GX_SET 


Description 


0 

src AND dst 

src AND NOT dst 

src 

(NOT src) AND dst 

dst 

src XOR dst 

src OR dst 

(NOT src) AND NOT dst 
(NOT src) XOR dst 
NOT dst 

src OR NOT dst 

NOT src 

(NOT src) OR dst 
(NOT src) OR NOT dst 
{ 


The screen the client is updating is the destination (dst). The graphics 
context the client uses to update the screen is the source (src). 
X$L_GCVL_FUNCTION specifies how the server computes new 
destination bits from the source (src) and the old bits of the destination 
(dst). 

The most common logical function is the default specified by the constant 


x$c_gx_copy, which only uses relevant values in the specified GC values 
data structure to update the screen. 


Specifies the planes on which the server performs the bitwise 
computation of pixels, defined by X$L_GCVL_FUNCTION. 


Because a monochrome display has only one plane, the plane mask 
value is given in the least significant bit of the longword. As planes are 
added to the display hardware, they are defined in the more significant 
bits of the mask. The display routine ALL PLANES specifies that ail 
planes of the display are referred to simultaneously. 


The server does not perform range checking on the plane mask. It 
truncates values to the appropriate number of bits. 


Specifies an index to a color map entry for foreground color. 
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Table 4-2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_BACKGROUND 
X$L_GCVL_LINE_WIDTH 


Contents 


Specifies an index to a color map entry for background color. 
Defines the width of a line in pixels. 


The server draws a line with a width of one or more pixels centered 

on the path described in the graphics request and contained within a 
bounding box. Unless otherwise specified by the join or cap style, the 
bounding box of a line with endpoints [ x1, y1], [ 22, y2] and width w > 0 
is a rectangle with vertices at the following real coordinates: 


{xl-w*sn/2, ylt+tw*cs/2], [xl+w*sn/2, yl-w*cs/2] 
[x2-w*sn/2, y2+tw*tes/2), [x2+w*sn/2, y2-w*cs/2] 


In this example, sn is the sine of the angle of the line. The symbol cs is 
the cosine of the angle of the line. A pixel is part of the line and is drawn 
if the center of the pixel is fully inside the bounding box. If the center 

of the pixel is exactly on the bounding box, the pixel is part of the line if 
and only if the interior is immediately to its right (x increasing direction). 
Pixels with centers on a horizontal edge are a special case and are part 
of the line if and only if the interior is immediately below the bounding box 
(y increasing direction). See Figure 4-2. 


Lines with zero line width are one pixel wide. The server draws them 
using an unspecified, device-dependent algorithm that imposes the 
following two constraints: 


* — If the server draws the line unclipped from [ 21, y4] to [ 22, y2], and 
if the server draws a second line from [ 21+ dz, y1+ dy] to [ s2+dz, 
y2 + dy], then point [ z, y] is touched by drawing the first line if and 
only if the point [ # + dz, y + dy] is touched by drawing the second 
line. 

* The effective set of points that compose a line cannot be affected by 
clipping. That is, a point is touched in a clipped line if and only if the 
point lies inside the clipping region and if the point would be touched 
by the line when drawn unclipped. 


A line more than one pixel wide drawn from [ 21, y1] to [ 22, y2] always 
draws the same pixels as a line of the same width drawn from [ 22, y2] to 
[ 21, y1], excluding cap and join styles. 


In general, drawing a line whose line width is zero is substantially faster 
than drawing a line whose line width is one or more. However, because 
the drawing algorithms for thin lines is different than those for wide lines, 
thin lines may not look as good when mixed with wide lines. If clients 
want precise and uniform results across all displays, they should always 
use a line width of one or more. Note, however, that specifying a line 
width of greater than zero decreases performance substantially. 
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Table 4~2 (Cont.) GC Values Data Structure Members 


Member Name Contents 

X$L_GCVL_LINE_STYLE Defines which sections of the line the server draws. The following lists 
available line styles and the constants that specify them: 
Constant Name Description 
x$c_line_solid The full path of the line is drawn. 
x$c_line_double_dash The full path of the line is drawn, but the 


even dashes are filled differently than the 
odd dashes, with cap butt style used where 
even and odd dashes meet. 

x$c_line_off_on_dash Only the even dashes are drawn. The 
X$L_CAP_STYLE member applies to all 
internal ends of dashes. Specifying the 
constant, x$c_cap_not_last, is equivalent to 
specifying x$c_cap_butt. 


Figure 4—3 illustrates the styles. 


X$L_GCVL_CAP_STYLE Defines how the server draws the endpoints of a path. The following lists 
available cap styles and the constants that specify them: 


Constant Name Description 

x$c_cap_butt Square at the endpoint (perpendicular to 
the slope of the line) with no projection 
beyond the endpoint 

x$c_cap_not_last Equivalent to specifying x$c_cap_butt, 


except that the final endpoint is not drawn if 
the line width is zero or one 


x$c_cap_round A circular arc with the diameter equal to 
the line width, centered on the endpoint 
(equivalent to specifying x$c_cap_butt for a 
line width of zero or one) 


x$c_cap_projecting Square at the end, but the path continues 
beyond the endpoint for a distance equal 
to half the width of the line (equivalent to 
specifying x$c_cap_butt for a line width of 
zero or one) 


Figure 4—4 illustrates the butt, round, and projecting cap styles. 
Figure 4—5 illustrates the style specified by the constant x$c_cap_ 
not_last. 





(continued on next page) 
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4.2 Defining Multiple Graphics Characteristics in One Call 


Table 4-2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_JOIN_STYLE 


Contents 


If a line has coincident endpoints ( 21 = 22, yl = y2), the cap style is 
applied to both endpoints with the following results: 


Line 

Constant Name Width Description 

x$c_cap_not_last Thin Device dependent, but the desired 
effect is that nothing is drawn. 

x$c_cap_butt Thin Device dependent, but the desired 
effect is that a single pixel is drawn. 

x$c_cap_butt Wide Nothing is drawn. 

x$c_cap_round Thin Device dependent, but the desired 
effect is that a single pixel is drawn. 

x$c_cap_round Wide The closed path is a circle, centered 
at the endpoint, with the diameter 
equal to the line width. 

x$c_cap_projecting Thin Device dependent, but the desired 
effect is that a single pixel is drawn. 

x$c_cap_projecting Wide The closed path is a square, aligned 


with the coordinate axes, centered 
at the endpoint with sides equal to 
the line width. 


Defines how the server draws corners for wide lines. Available join styles 
and the constants that specify them are as follows: 


Constant Name Description 

x$c_join_mitre The outer edges of the two lines extend to meet 
at an angle. 

x$c_join_round A circular arc with diameter equal to the line 
width, centered at the join point. 

x$c_join_bevel Cap butt endpoint style, with the triangular notch 
filled. 


Figure 4-6 illustrates the styles. 


For a line with coincident endpoints ( 21 = 22, y1 = y2), when the join 
style is applied at one or both endpoints, the effect is as if the line were 
removed from the overall path. However, if the total path consists of (or 
is reduced to) a single point joined with itself, the effect is the same as if 
the X$L_GCVL_CAP_STYLE were applied to both endpoints. 





(continued on next page) 
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Table 4—2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_FILL_STYLE 


Contents 


Specifies the contents of the source for line, text, and fill operations. The 
following lists available fill styles for text and fill requests (DRAW TEXT, 
DRAW TEXT 16, FILL RECTANGLE, FILL POLYGON, FILL ARC). It also 
lists available styles applicable to solid lines and even dashes resulting 
from line requests (LINE, SEGMENTS, RECTANGLE, ARC): 


Constant Name 


x$c_fill_solid 
x$c_fill_tiled 
x$c_fill_opaque_stippled 


x$c_fill_stippled 


Description 


Foreground 
Tile 


A tile with the same width and height as 
stipple but with background everywhere 
stipple has a zero and with foreground 
everywhere stipple has a one 


Foreground masked by stipple 


The following lists available styles applicable to odd dashes resulting 


from line requests: 


Constant Name 


x$c_fill_solid 
x$c_fill_tiled 
x$c_fill_opaque_stippled 


x$c_fill_stippled 


Description 


Background 

Tile 

A tile with the same width and height as 
stipple but with background everywhere 


stipple has a zero and with foreground 
everywhere stipple has a one 


Background masked by stipple 
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Table 4-2 (Cont.) GC Values Data Structure Members 





Member Name 


X$L_GCVL_FILL_RULE 


X$L_GCVL_ARC_MODE 


X$L_GCVL_TILE 


Contents 


Defines what pixels the server draws along a path when a polygon is 
filled (see Section 6.5.2). The two available choices are x$c_even_odd_ 
rule and x$c_winding_rule. The x$c_even_odd_rule constant defines 

a point to be inside a polygon if an infinite ray with the point as origin 
crosses the path an odd number of times. If the point meets these 
conditions, the server draws a corresponding pixel. 


The x$c_winding_rule constant defines a point to be inside the polygon 

if an infinite ray with the pixel as origin crosses an unequal number of 
clockwise-directed and counterclockwise-directed path segments. A 
clockwise-directed path segment is one that crosses the ray from left to 
right as observed from the pixel. A counterclockwise-directed segment 

is one that crosses the ray from right to left as observed from that point. 
When a directed line segment coincides with a ray, choose a different ray 
that is not coincident with a segment. If the point meets these conditions, 
the server draws a corresponding pixel. 


For both even odd rule and winding rule, a point is infinitely small, and 
the path is an infinitely thin line. A pixel is inside the polygon if the center 
point of the pixel is inside, and the center point is not on the boundary. 

lf the center point is on the boundary, the pixel is inside if and only if 

the polygon interior is immediately to its right (x increasing direction). 
Pixels with centers along a horizontal edge are a special case and are 
inside if and only if the polygon interior is immediately below (y increasing 
direction). 


Figure 4~7 illustrates fill rules. Figure 4-8 illustrates rules for filling a 
pixel when it falls on a boundary. 


Controls how the server fills an arc. The available choices are specified 
by the constants x$c_arc_pie_slice and x$c_arc_chord. Figure 4—9 
illustrates the two modes. 


Specifies the pixmap the server uses for tiling operations. The pixmap 
must have the same root and depth as the graphics context, or an error 
occurs. Clients can use any size pixmap for tiling, although some sizes 
produce a faster response than others. To determine the optimum size, 
use the QUERY BEST SIZE routine. 


Storing a pixmap in a graphics context might or might not result in a copy 
being made. If the pixmap is later used as the destination for a graphics 
request, the change might or might not be reflected in the graphics 
context. If the pixmap is used simultaneously in a graphics request both 
as a destination and as a tile, the results are not defined. 


(continued on next page) 
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Table 4-2 (Cont.) GC Values Data Structure Members 


Member Name 


X$L_GCVL_STIPPLE 


X$L_GCVL_TS_X_ORIGIN 


X$L_GCVL_TS_Y_ORIGIN 


X$L_GCVL_FONT 
X$L_GCVL_SUBWINDOW_MODE 


X$L_GCVL_GRAPHIC_EXPOSURES 
X$L_GCVL_CLIP_X_ORIGIN 
X$L_GCVL_CLIP_Y_ORIGIN 


X$L_GCVL_CLIP_MASK 


Contents 


Specifies the pixmap the server uses for stipple operations. The pixmap 
must have the same root as the graphics context and a depth of one, 

or an error occurs. For stipple operations where the fill style is specified 
as x$c_fill_stippled but not x$c_fill_opaque_stipple constant, the stipple 
pattern is tiled in a single plane and acts as an additional clip mask. 
Perform a bitwise AND operation with the clip mask. Clients can use any 
size pixmap for stipple operations, although some sizes produce a faster 
response than others. To determine the optimum size, use the QUERY 
BEST SIZE routine. 


Defines the origin for tiling and stipple operations. Origins are relative 
to the origin of whatever window or pixmap is specified in the graphics 
request. 


Defines the origin for tiling and stipple operations. Origins are relative 
to the origin of whatever window or pixmap is specified in the graphics 
request. 


Specifies the font that the server uses for text operations. 


Specifies whether or not inferior windows clip superior windows. The 
constant x$c_clip_by children specifies that all viewable input-output 
children clip both source and destination windows. The constant 
x$c_include_inferiors specifies that inferiors clip neither source nor 
destination windows. This results in drawing through subwindow 
boundaries. The semantics of using the constant on a window with a 
depth of one and with mapped inferiors of differing depth is undefined by 
the core protocol. 


- Specifies whether or not the server informs the client when the contents 


of a window region are lost. 


Defines the x-coordinate of the clip origin. The clip origin specifies the 
point within the clip region that is aligned with the drawable origin. 


Defines the y-coordinate of the clip origin. The clip origin specifies the 
point within the clip region that is aligned with the drawable origin. 


Identifies the pixmap the server uses to restrict write operations to the 
destination drawable. The pixmap must have a depth of one and have 
the same root as the graphics context. The clip mask clips only the 
destination drawable, not the source drawable. Where a value of one 
appears in the mask, the corresponding pixel in the destination drawable 
is drawn; where a value of zero occurs, no pixel is drawn. Any pixel 
within the destination drawable that is not represented within the clip 
mask pixmap is not drawn. When a client specifies the value of clip mask 
as x$c_none, the server draws all pixels. 
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Table 4—2 (Cont.) GC Values Data Structure Members 


Member Name Contents 


X$L_GCVL_DASH_OFFSET Specifies the pixel within the dash length sequence, defined by 
X$B_GCVL_DASHES, to start drawing a dashed line. For example, a 
dash offset of zero starts a dashed line as the beginning of the dash line 
sequence. A dash offset of five starts the line at the fifth pixel of the line 
sequence. 


X$B_GCVL_DASHES Specifies the length, in number of pixels, of each dash. The value of this 
member must be nonzero or an error occurs. 


Figure 4-2. Bounding Box 
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Figure 4-3 Line Styles 
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Figure 4-4 Butt, Round, and Projecting Cap Styles 
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Figure 4—5 Cap Not Last Style 
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Figure 4-6 Join Styles 
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Figure 4-7 Fill Rules 
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Figure 4-8 Pixel Boundary Cases 
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Figure 4-9 Styles for Filling Arcs 


Chord 


Pie Slice 


~ 


ZK-0008A-GE 


4-15 


Defining Graphics Characteristics 
4.2 Defining Multiple Graphics Characteristics in One Call 


4-16 


Figure 4-10 Dashed Line Offset 
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Xlib assigns a flag for each member of the GC values data structure to 
facilitate referring to members (Table 4-3). 


Table 4-3 GC Values Data Structure Flags 


Flag Name 


x$m_gc_function 
x$m_gce_plane_mask 
x$m_gc_foreground 
x$m_gc_background 
x$m_gce_line_width 
x$m_gc_line_style 
x$m_gc_cap_style 
x$m_gc_join_style 
x$m_gc_fill_style 
x$m_gc_fill_rule 
x$m_gc_tile 
x$m_gc_siippie 
x$m_gc_tile_stip_x_origin 
x$m_gc_tile_stip_y_origin 
x$m_ge_font 
x$m_ge_subwindow_mode 
x$m_ge_graphics_exposures 
x$m_gc_clip_x_origin 


GC Values Member 


X$L_GCVL_FUNCTION 
X$L_GCVL_PLANE_MASK 
X$L_GCVL_FOREGROUND 
X$L_GCVL_BACKGROUND 
X$L_GCVL_LINE_WIDTH 
X$L_GCVL_LINE_STYLE 
X$L_GCVL_CAP_STYLE 
X$L_GCVL_JOIN_STYLE 
X$L_GCVL_FILL_STYLE 
X$L_GCVL_FILL_RULE 
X$L_GCVL_TILE 
X$L_GCVL_STIPPLE 
X$L_GCVL_TS_X_ORIGIN 
X$L_GCVL_TS_Y_ORIGIN 
X$L_GCVL_FONT 
X$L_GCVL_SUBWINDOW_MODE 
X$L_GCVL_GRAPHICS_EXPOSURES 
X$L_GCVL_CLIP_X_ORIGIN 


(continued on next page) 


Defining Graphics Characteristics 
4.2 Defining Multiple Graphics Characteristics in One Call 


Table 4-3 (Cont.) GC Values Data Structure Flags 


Flag Name GC Values Member 
x$m_gc_clip_y_origin X$L_GCVL_CLIP_Y_ORIGIN 
x$m_ge_clip_mask X$L_GCVL_CLIP_MASK 
x$m_gc_dash_offset X$L_GCVL_DASH_OFFSET 
x$m_gce_dash_list X$B_GCVL_DASHES 
x$m_gc_arc_mode X$L_GCVL_ARC_MODE 


Example 4-1 illustrates how a client can define graphics context values 
using the CREATE GC routine. Figure 4-11 shows the resulting output. 


Example 4-1 Defining Graphics Characteristics Using the CREATE GC Routine 


INTEGER*4 GC 
INTEGER*4 GC_MASK 
RECORD /X$GC_VALUES/ XGCVL 


100, Y1 100, 
550, Y2 550 


PARAMETER X1 
1 X2 


Create the graphics context 


@ooa 


GC_MASK = X$M_GC_FOREGROUND .OR. X$M_GC_BACKGROUND .OR. 
1 X$M_GC_LINE WIDTH .OR. X$M_GC_LINE_STYLE .OR. X$M_GC_DASH_OFFSET 
1 .OR. X$M_GC DASH LIST 


2) XGCVL.X$L_GCVL_FOREGROUND = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 3) 


XGCVL.XSL_GCVL_BACKGROUND = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 4) 


XGCVL.X$L_GCVL_LINE_WIDTH = 4 
XGCVL.X$L_GCVL_LINE STYLE = X$C_LINE DOUBLE_DASH 
XGCVL.X$L_GCVL_DASH_ OFFSET = 0 
XGCVL.X$B_GCVL_DASHES = 25 


3] GC = XSCREATE_GC(DPY, WINDOW, GC_MASK, XGCVL) 


o- CALL X$DRAW_LINE(DPY, WINDOW, GC, Xl, Y1, X2, ¥2) 
@ Specify the members of the GC values data structure that will have 
assigned values. 


@ Specify the foreground, background, line width, line style, dash offset, 
and dashes for line drawing. 


The dashed line is four pixels wide. A dash offset value of zero starts 
dashes at the beginning of the line. The dashes value specifies that 
dashes be 25 pixels long. 
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© The CREATE GC routine loads values into a GC data structure. The 
CREATE GC routine has the following format: 


gc_id = XS$CREATE_GC (display, drawable_id, gc_mask, 
values_ struc) 


@ See Chapter 6 for information about drawing lines. 


Figure 4-11 Dashed Line 


Dashed Line 


Click MB1 to draw a dashed line. 
Click MB3 to exit. 
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4.3 Defining Individual Graphics Characteristics 


Xlib offers routines that enable clients to define individual or functional 
groups of graphics characteristics. Table 4—4 lists and briefly describes 
these routines. For more information about the components, see 
Section 4.1. 
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Table 4-4 Routines That Define Individual or Functional Groups of 
Graphics Characteristics 


Routine 


Description 


Foreground, Background, Plane Mask, and Function Routines 


SET STATE 


SET FOREGROUND 
SET BACKGROUND 
SET PLANE MASK 
SET FUNCTION 


Line Attribute Routines 
SET LINE ATTRIBUTES 

SET LINE DASHES 

Fill Style and Rule Routines 
SET FILL STYLE 


SET FILL RULE 


Fill Tile and Stipple Routines 
QUERY BEST SIZE 


QUERY BEST STIPPLE 
QUERY BEST TILE 


SET STIPPLE 
SET TILE 
SET TS ORIGIN 


Font Routine 


SET FONT 


Sets the foreground, background, plane mask, 
and function 


Sets the foreground 
Sets the background 
Seis the plane mask 
Sets the function 


Sets line width, line style, cap style, and join 
style 


Sets the dash offset and dash list of a line 


Sets fill style to solid, tiled, stippled, or opaque 
stippled 


Sets fill rule to either even and odd or winding 
rule 


Queries the server for the size closest to the 
one specified 


Queries the server for the closest stipple 
shape to the one specified 


Queries the server for the closest tile shape to 
the one specified 


Sets the stipple pixmap 
Sets the tile pixmap 
Sets the tile or stipple origin 


Sets the current font 


(continued on next page) 
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Table 4—4 (Cont.) Routines That Define Individual or Functional Groups 
of Graphics Characteristics 


Routine Description 


Clip Region Routines 


SET CLIP MASK Sets the mask for bitmap clipping 
SET CLIP ORIGIN Sets the origin for clipping 
SET CLIP RECTANGLES Changes the clip mask from its current value 


to the specified rectangles 


Arc, Subwindow, and Exposure Routines 


SET ARC MODE Sets the arc mode to either chord or pie slice 


SET SUBWINDOW MODE Sets the subwindow mode to either clip by 
children or include inferiors 
SET GRAPHICS EXPOSURES Specifies whether exposure events are created 


when calling COPY AREA or COPY PLANE 


Example 4-2 illustrates using individual routines to set background, 
foreground, and line attributes. Figure 4-12 illustrates the resulting 
output. 


Example 4—2 Using Individual Routines to Define Graphics Characteristics 
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BYTE DASH_LIST(3) 
DATA DASH_LIST /20,5,10/ 


PARAMETER X1 = 100, Y1 = 100, 
1 X2 = 550, Y2 = 550 


CALL X$SET_BACKGROUND (DPY, GC, DEFINE COLOR(DPY, SCREEN, 
1 VISUAL, 4)) 


CALL X$SET_LINE_ATTRIBUTES (DPY, GC, 10, 
1 X$C_LINE _DOUBLE_DASH, 0, 0) 


CALL X$SET DASHES (DPY, GC, 0, DASH LIST, 3) 
CALL XSDRAW_LINE(DPY, WINDOW, GC, X1, Y1, X2, Y2) 


@ DASH _LIST defines the length of odd and even dashes. The first and 
third elements of the initialization list specify even dashes; the second 
element specifies odd dashes. 


@ The SET LINE ATTRIBUTES routine enables the client to define line 
width, style, cap style, and join style in one call. 


The SET LINE ATTRIBUTES routine has the following format: 


XSSET_LINE ATTRIBUTES (display, gc_id, line_width, 
line style, cap_style, join_style) 


The zero cap_style argument specifies the default cap style. 
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© When using the CREATE GC routine to set line dashes, odd and even 
dashes must have equal length. The SET DASHES routine enables the 
client to define dashes of varying length. The SET DASHES routine 
has the following format: 


XSSET_ DASHES (display, gc_id, dash_offset, dash_list, 
dash_list_len) 


The dash_list_len argument specifies the length of the dash list. 


Figure 4-12 Line Defined Using GC Routines 


Line Defined with GC Convenience Routines LHI 


Click MB1 to draw a dashed line. 
Click MB3 to exit. 
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4.4 Copying, Changing, and Freeing Graphics Contexts 


In addition to defining a graphics context, clients can copy defined 
characteristics from one GC data structure into another. To copy a GC 
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data structure, use COPY GC. The COPY GC routine has the following 
format: 
XSCOPY_GC(display, src_gc_id, gc_mask, dst_gc_id) 


The gc_mask argument selects values to be copied from the source 
graphics context (sre_gc_id). Use the method described in Section 4.2 
for assigning values to a GRAPHICS CONTEXT. 


The dst_ge_id argument specifies the new graphics context into which the 
server copies values. 


After creating a graphics context structure, change values as needed using 
CHANGE GC. The following code fragment, which alters the values of 
the line drawn by Example 4-1, illustrates changing a graphics context 
structure: 


GC_MASK = X$M_GC_LINE_ WIDTH .OR. X$M_GC_LINE_STYLE 
XGCVL.X$L_GCVL_LINE_WIDTH = 10 
XGCVL.X$L_GCVL_LINE_STYLE = X$C_LINE_SOLID 

CALL X$CHANGE_GC(DPY, GC, GC_MASK, XGCV) 


The example illustrates defining a new line style and width, and changing 
the graphics context to include the new values. 


4.5 Using Graphics Characteristics Efficiently 
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The server must revalidate a graphics context whenever a client redefines 
it. Causing the server to revalidate a graphics context unnecessarily can 
seriously degrade performance. 


The server revalidates a graphics context when one of the following 
conditions occurs: 


¢ A client associates the graphics context with a different window. 


* The graphics context clip list changes. Changes in the clip list can 
happen either when a client changes the graphics context clip origin 
or when the server modifies the clip list in response to overlapping 
windows. 


* Any member of the graphics context changes. 


To minimize revalidating the graphics context, submit as a group the 
requests to the server that identify the same window and graphics context. 
Grouping requests enables the server to revalidate the graphics context 
once instead of many times. 


When it is necessary to change the value of graphics context members 
frequently, creating a new graphics context is more efficient than 
redefining an existing one, provided the client creates no more than 50 
graphics contexts. 


5 Using Color 


Color is one attribute clients can define when creating a window or a 
graphics object. Depending on display hardware, clients can define color 
as black or white, as shades of gray, or as a spectrum of hues. Section 5.2 
describes color definition in detail, including workstation types and the 
colors they support. 


Xlib offers clients the choice of either sharing colors with other clients or 
allocating colors for exclusive use. 


A client that does not have to change colors can share them with other 
clients. By sharing colors, the client saves color resources. 


A client must allocate colors for its exclusive use when it needs to change 
them. For example, when presenting a graphic representation of a 
pipeline, the client might indicate flow through the pipeline by changing 
colors rather than redrawing the entire pipeline schematic. In this case, 
the client would allocate for exclusive use colors that represent pipeline 
flow. 


This chapter introduces color management using Xlib and describes how 
to share and allocate color resources, The chapter includes the following 
topics: 


¢ Color fundamentals—A description of pixels and planes, and color 
indices, cells, and maps 


¢ Matching color requirements to screen types— How screen types affect 
color presentation 


¢ Sharing color resources—How to share color resources with other 
clients 


e Allocating colors for exclusive use—How to reserve colors for a single 
client 


* Querying color resources—How to return values of color map entries 
¢ Freeing color resources—How to release color resources 
The concepts presented in this chapter apply to managing the color of both 


windows and graphic objects. Chapter 6 describes how to create graphic 
objects. 





5.1 Pixels and Color Maps 


The color of a window or graphics object depends on the values of 

pixels that constitute it. The number of bits associated with each pixel 
determines the number of possible pixel values. On a monochrome screen, 
one bit maps to each pixel. The number of possible pixel values is two. 
Pixels are either zero or one, black or white. 
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On a monochrome screen, all bits that define an image reside on 
one plane, an allocation of memory in which there is a one-to-one 
correspondence between bits and pixels. The number of planes is the 
depth of the screen. 


The depth of intensity or color screens is greater than one. More than one 
bit defines the value of a pixel. Each bit associated with the pixel resides 
on a different plane. 


The number of possible pixel values increases as depth increases. For 
example, if the screen has a depth of four planes (hardware will support 
a four-plane screen), the value of each pixel comprises four bits. Clients 
using a four-plane intensity display can produce up to sixteen levels of 
brightness. Clients using a four-plane color display can produce as many 
as sixteen colors. 


Figure 5-1 illustrates the relationship between pixel values and planes. 


Figure 5—1 Pixel Values and Planes 
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Xlib uses color maps to define the color of each pixel. A color map 
contains a collection of color cells, each of which defines the color pixel 
value in terms of its red, green, and blue (RGB) components. Red, green, 
and blue components are in the range of zero (off) to 65535 (brightest) 
inclusive. 


Each pixel value refers to a location in a color map, or is an index into a 
color map. For example, the pixel value illustrated in Figure 5—1 indexes 
color cel] 11 in Figure 5-2. 
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Figure 5-2 Color Map, Cell, and Index 
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Because most VAXstations have a hardware color map that is global to the 
entire display, clients should use the same color map whenever possible. 
Otherwise, some clients will appear in the wrong color. 


For example, an image processing program that requires 128 colors might 
allocate and store a color map of these values. To alter some colors, 
another client may invoke a color palette program that chooses and mixes 
colors. The color palette program itself requires a color map, which the 
program allocates and installs. 


Since both programs have allocated different color maps, this can produce 
undesirable results. When the image processing program runs, the color 
palette image may be incorrectly displayed because only the image 
processing color map is installed. Conversely, when the color palette 
program runs, the image processing program may be incorrectly displayed 
because only the color palette color map is installed. 
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Xlib reduces the problem of contending for color resources in two ways. 
First, Xlib provides a default color map to which all clients have access. 
Second, clients can either allocate color cells for exclusive use or allocate 
colors for shared use from the default color map. By sharing colors, a 
client can use the same color cells as other clients. This method conserves 
space in the default color map. 


In cases where the client cannot use the default color map and must use 
a new color map, Xlib creates virtual color maps. The use of virtual color 
maps is analogous to the use of virtual memory in a multiprogramming 
environment where many processes must access physical memory. When 
concurrent processes collectively require more color map entries than exist 
in the hardware color map, the color values are swapped in and out of the 
hardware color map. However, swapping virtual color maps in and out of 
the hardware color map causes contention for color resources. Therefore, 
the client should avoid creating color maps whenever possible. 


The process of loading or unloading color values of the virtual color map 
into the hardware lookup table occurs when a client calls the INSTALL 
COLORMAP or UNINSTALL COLORMAP routines. Typically, the 
privilege to install or remove color maps is restricted to the window 
manager. 


5.2 Matching Color Requirements to Screen Types 
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Each screen has a list of visual types associated with it. The visual type 
identifies the characteristics of the screen, such as color or monochrome 
capability. Visual types partially determine the appearance of color on 
the screen and determine how a client can manipulate color maps for a 
specified screen. 


Color maps can be manipulated in a variety of ways on some hardware, 
in a limited way on other hardware, and not at all on yet other hardware. 
For example, a screen may be able to display a full range of colors or a 
range of grays only, depending on its visual type. 


VMS DECwindows supports the following visual types: 


* Pseudocolor—A pixel value indexes a color map to produce independent 
RGB values. RGB values can be changed dynamically, if a pixel has 
been allocated for exclusive use. 


¢ Gray scale—Same as pseudocolor, except the pixel value indexes a 
color map that produces only shades of gray. 


¢ Static gray—Same as gray scale, except that clients cannot change 
values in the color map. 


In addition to supporting pseudocolor, gray scale, and static gray, VMS 
DECwindows enables clients to simulate the direct color visual type. 
Direct color stores RGB components into three separate data structures: 
one for red values, one for green values, and one for blue values. Pixel 
values refer to these three data structures, as Figure 5-3 illustrates. A 
direct color pixel value of 000000010, or 000 000 010, refers to member 
0 of the data structure of red values, member 0 of the data structure of 
green values, and member 2 of the data structure of blue values. 


Using Color 
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See Section 5.4.2 for information about simulating a direct color device. 


Figure 5-3 Visual Types and Color Map Characteristics 
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Default visual types are defined for each screen of a display and depend on 
the workstation and monitor type. 
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Table 5—1 lists VAXstations and their visual types. 


Table 5-1 VAXstation Visual Types 


Visual Type 
Monochrome Color 

VAXstation Type Monitor Monitor 
VAXstation II Static gray N/A 
VAXstation 2000 Static gray N/A 
VAXstation l/GPX Gray scale Pseudocolor 
VAXsiation 2000/GPX Gray scale Pseudocolor 
VAXstation 3200 Gray scale Pseudocolor 
VAXstation 3500 Gray scale Pseudocolor 


Before defining colors, use the following method to determine the visual 
type of a screen: 


1 Use the DEFAULT VISUAL OF SCREEN routine to determine the 
identifier of the visual. Xlib returns the identifier to a visual data 
structure. 


2 Refer to the X$L_VISU_CLASS member of the data structure to 
determine the visual type. 


The following example illustrates how to determine the visual type of a 
screen: 


CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_COLOR .OR. 
1  VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT COLOR) THEN 
COLOR_MAP = XSDEFAULT_COLORMAP_OF_SCREEN (SCRN) 





5.3 Sharing Color Resources 
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Xlib provides the following ways to share color resources: 
¢ Using named VMS DECwindows colors 


¢ Specifying exact color values 


The choice of using a named color or specifying an exact color depends on 
the needs of the client. For instance, if the client is producing a bar graph, 
specifying the named VMS DECwindows color “Red” as a color value may 
be sufficient, regardless of the hue that VMS DECwindows names “Red”. 


5.3.1 


Using Color 
5.3 Sharing Color Resources 


However, if the client is reproducing a portrait, specifying an exact red 
color value might be necessary to produce accurate skin tones. 


Note that because of differences in hardware, no two monitors display 
colors exactly the same even though the same named colors are specified. 


For a list of named VMS DECwindows colors, see Appendix C. 


Using Named VMS DECwindows Colors 


VMS DECwindows includes named colors that clients can share. To use a 
named color, call the ALLOC NAMED COLOR routine. ALLOC NAMED 
COLOR determines whether the color map defines a value for the specified 
color. If the color exists, the server returns the index to the color map. If 
the color does not exist, the server returns an error. 


Example 5-1 illustrates specifying a color using ALLOC NAMED COLOR. 
Example 5-1 Using Named VMS DECwindows Colors 


INTEGER*4 FUNCTION DEFINE COLOR(DISP, SCRN, VISU, N) 
INCLUDE ‘SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, N 

RECORD /XSVISUAL/ VISU ! visual type 

RECORD /X$COLOR/ SCREEN COLOR 

INTEGER*4 STR_SIZE, STATUS, COLOR_MAP 

CHARACTER*15 COLOR_NAME (3) 

DATA COLOR_NAME /'DARK SLATE BLUE’, ’LIGHT GREY ', ‘PIREBRICK ‘/ 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO COLOR .OR. 
1  VISU.XS$L_VISU_CLASS .EQ. X$C_DIRECT COLOR) THEN 


COLOR_MAP = XS$DEFAULT_COLORMAP_OF_SCREEN (SCRN) 
STATUS = STRSTRIM(COLOR_NAME (N), 
1 COLOR_NAME(N), STR_SIZE) 
STATUS = XSALLOC_NAMED_ COLOR (DISP, COLOR _MAP, 
L COLOR_NAME (N) (1:STR_SIZE), SCREEN_COLOR) 
IF (STATUS .NE. 0) THEN 
DEFINE COLOR = SCREEN_COLOR.X$L_COLR_PIXEL 
ELSE 
WRITE(6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL ($VAL (STATUS) ) 
DEFINE COLOR = 0 
END IF 
ELSE 
IF (N .EQ. 1 .OR. N .EQ. 3) 
1 DEFINE COLOR XS$BLACK_ PIXEL OF_SCREEN (DISP) 


o 9o 


IF (N .EQ. 2 ) 
1 DEFINE COLOR 
END IF 


XSWHITE PIXEL OF SCREEN (DISP) 


RETURN 
END 





@ Allocate storage for a color data structure that defines the closest RGB 
values supported by the hardware. 
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5.3.2 
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5.3 Sharing Color Resources 


For an illustration of the color data structure, see Section 5.3.2. 


@ Create an array to store the names of predefined VMS DECwindows 
colors used by the client. In the sample program, the client uses 
three named colors: dark slate blue, light grey, and firebrick. When 
allocating a color, the client refers to the array element that stores the 
appropriate named VMS DECwindows color. 


© Xlib requires clients to pass names of predefined colors without 
padding. In the DEFINE_COLOR function, the names of predefined 
colors are stored in an array of three 15-byte members. Because the 
names “light grey” and “firebrick” require less than 15 bytes of storage, 
they are padded. 


To pass the names without padding, use the system-define procedure 
STR$TRIM, which returns to the STR_SIZE variable the length of the 
string minus any trailing blanks. 


@ The ALLOC NAMED COLOR routine has the following format: 


XSALLOC_NAMED COLOR(display, colormap_id, color_name, 
[screen_def return], [exact_def_return]) 


The client refers to array COLOR_NAME to pass the name of the 
color. The client passes only the substring that contains the predefined 
name; blanks used to pad the array are ignored. 


Specifying Exact Color Values 


To specify exact color values, use the following method: 
1 Assign values to a color data structure 


2 Call the ALLOC COLOR routine, specifying the color map that stores 
the definition. ALLOC COLOR returns a pixel value and changes the 
RGB values to indicate the closest color supported by the hardware. 


Xlib provides a color data structure to enable clients to specify exact color 
values when sharing colors. (Routines that allocate colors for exclusive 
use and that query available colors also use the color data structure. For 
information about using the color data structure for these purposes, see 
Section 5.4.) 


Figure 5-4 illustrates the color data structure. 


Figure 5-4 Color Data Structure 










5-8 






x$l_colr_pixel 0 
x$b_colr_pad x$b_colr_flags x$w_colr_blue 8 


Using Color 
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Table 5—2 describes the members of the data structure. 


Table 5-2 Color Data Structure Members 


Member Name Contents 

X$L_COLR_PIXEL Pixel value. 

X$W_COLR_RED Defines the red value of the pixel ' 

X$W_COLR_GREEN Defines the green value of the pixel ' 

X$W_COLR_BLUE Defines the blue value of the pixel ' 

X$B_COLR_FLAGS Defines which color components are to be changed in 
the color map. Possible flags are as follows: 
x$m_do_red Sets red values 
x$m_do_green Sets green values 
x$m_do_blue Sets blue values 

X$B_COLR_PAD Makes the data structure an even length 


'Color values are scaled between 0 and 65535. “On full” in a color is a value of 65535, 
independent of the number of planes of the display. Half brightness in a color is a value of 
32767; off is a value of 0. This representation gives uniform results for color values across 
displays with different color resolution. 


Example 5—2 illustrates how to specify exact color definitions. 


Example 5-2 Specifying Exact Color Values 


Cc Create color 
G 
INTEGER*4 FUNCTION DEFINE _COLOR(DISP, SCRN, VISU, N) 


INCLUDE 'SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, N 

RECORD /X$VISUAL/ VISU ! visual type 
RECORD /X$COLOR/ COLORS (3) 

INTEGER*4 STATUS, COLOR_MAP 

INTEGER*4 FLAGS 


(continued on next page) 
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Example 5~2 (Cont.) Specifying Exact Color Values 





IF (VISU.X$L_VISU_CLASS .£Q. X$C_PSEUDO COLOR .OR. 
1  VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT COLOR) THEN 
1) FLAGS = X$M_DO RED .OR. X$M_DO GREEN .OR. X$M DO BLUE 
COLOR_MAP = X$DEFAULT_COLORMAP OF SCREEN (SCRN) 
IF (N .EQ. 1) THEN 
COLORS (N) .X$B_COLR_FLAGS = FLAGS 


e COLORS (N) .X$W_COLR_RED = 59904 
COLORS (N) .X$W_COLR_GREEN = 44288 
COLORS (N) .X$W_COLR_BLUE = 59904 
13) STATUS = X$ALLOC_COLOR(DISP, COLOR_MAP, COLORS (N) ) 
IF (STATUS .NE. 0) THEN 
DEFINE COLOR = COLORS (N) .X$L_COLR_PIXEL 
ELSE 
WRITE (6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL ($VAL (STATUS) ) 
DEFINE_COLOR = 0 
END IF 
ELSE IF (N. EQ. 2) THEN 
COLORS (N) .X$B_COLR_FLAGS = FLAGS 
COLORS (N) .X$W_COLR_RED = 65280 
COLORS (N) .X$W_COLR_GREEN = 0 
COLORS (N) .X$W_COLR_BLUE = 32512 
STATUS = XSALLOC_COLOR (DISP, COLOR_MAP, COLORS (N) ) 
IF (STATUS .NE. 0) THEN 
DEFINE COLOR = COLORS (N) .X$L_COLR_PIXEL 
ELSE 
WRITE (6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
DEFINE COLOR = 0 
END IF 
ELSE IF (N. EQ. 3) THEN 
COLORS (N) .X$B_COLR_FLAGS = FLAGS 
COLORS (N) .X$W_COLR_RED = 37632 
COLORS (N) .X$W_COLR_GREEN = 56064 
COLORS (N) .X$W_COLR_BLUE = 28672 
STATUS = XSALLOC_COLOR(DISP, COLOR_MAP, COLORS (N) ) 
IF (STATUS .NE. 0) THEN 
DEFINE COLOR = COLORS (N) .X$L_COLR_PIXEL 
ELSE 
WRITE (6,*) ‘Color not allocated!’ 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
DEFINE COLOR = 0 


END IF 
END IF 
ELSE 
IF (N .EQ. 1 .OR. N .EQ. 3) 
1 DEFINE COLOR = X$BLACK_PIXEL_OF_SCREEN (DISP) 


IF (N .EQ. 2 ) 
1 DEFINE COLOR 
END IF 


XSWHITE_PIXEL OF _SCREEN (DISP) 


RETURN 
END 





@ FLAGS specifies that RGB values are defined. 


@ Define color values in the first of three color data structures. 
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© After defining RGB values, call the ALLOC COLOR routine. ALLOC 
COLOR allocates shared color cells on the default color map and 
returns a pixel value for the color that matches the specified color most 
closely. 


5.4 Allocating Colors for Exclusive Use 


A client that does not need to change color values should share colors using 
the methods described in Section 5.3.2. Sharing colors saves resources. 
However, a client that changes color values must allocate them for its 
exclusive use. 


Xlib provides two methods for allocating colors for the exclusive use of 
a client. First, the client can allocate cells and store color values in the 
default color map. Second, if the default color map does not contain 
enough storage, the client can create its own color map and store color 
values in it. 


This section describes how to specify a color map, how to allocate cells for 
exclusive use, and how to store values in the color cells. 


5.4.1. Specifying a Color Map 


Clients can either use the default color map and allocate its color cells for 
exclusive use or create their own color maps. 


If possible, use the default color map. Although a client can create color 
maps for its own use, the hardware color map storage is limited. When a 
client creates its own color map, the map must be loaded, or installed, into 
the hardware color map before the client map can be used. If the client 
color map is not installed, the client may refer to a different color map and 
possibly display the wrong color. Using the default color map eliminates 
this problem. See Section 5.1 for information about how Xlib handles color 
maps. 


To specify the default color map, use the DEFAULT COLORMAP routine. 
DEFAULT COLORMAP returns the identifier of the default color map. 


If the default color map does not contain enough resources, the client can 
create its own color map. 


To create a color map, use the following method: 


1 Determine the visual type of a specified screen using the method 
described in Section 5.2 


2 Call the CREATE COLORMAP routine. 


The CREATE COLORMAP routine creates a color map for the specified 
window and visual type. CREATE COLORMAP has the following format: 


X$CREATE_COLORMAP (display, window_id, visual_struc, alloc) 


511 


5.4.2 
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The alloc argument specifies whether the client creating the color map 
allocates all of the color map entries for its exclusive use or creates a 
color map with no allocated color map entries. To allocate all entries for 
exclusive use, specify the constant x$c_alloc_all. To allocate no defined 
map entries, specify the constant x$c_alloc_none. The latter is useful 
when two or more clients are to share the newly created color map. 


If the visual type is pseudocolor or gray scale, the client can either allocate 
all or no map entries. If the visual type is static gray, the client must 
allocate no entries. 


See Section 5.4.2 for information about allocating colors. See Example 5-3 
for an example of specifying the default color map. 


Allocating Color Cells 


After specifying a color map, allocate color cells in it. 


To allocate color cells, call the ALLOC COLOR CELLS routine to allocate 
cells for a pseudocolor device or a gray scale device. Call the ALLOC 
COLOR PLANES routine to simulate a direct color device. See Section 5.2 
for information about the direct color visual type. 


Example 5-3 illustrates how to allocate colors for exclusive use. The 
program creates a color wheel that rotates when the user presses MB1. 


Example 5-3 Allocating Colors for Exclusive Use 


PROGRAM COLOR_WHEEL 


INCLUDE /’SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER*4 
INTEGER* 4 
INTEGER* 4 
INTEGER*4 
INTEGER* 4 
INTEGER*4 
INTEGER*4 
INTEGER* 4 


DPY 


SCREEN 
WINDOW 


GC_! 


ATT 
GC 

OFF 
OFF 


MASK 
R_MASK 


SET_X 
SET Y 


CMAP 
PIXMAP 


WID 
BUT 


TH, HEIGHT 
TON_IS_DOWN 


FULL_COUNT 
STATUS, FUNC 
WINDOW_X, WINDOW_Y, DEPTH 


RECORD /XSVISUAL/ VISUAL 

RECORD /X$COLOR/ COLORS (128) 

RECORD /XS$SET_WIN_ATTRIBUTES/ XSWDA 

RECORD /X$GC_VALUES/ XGCVL 

RECORD /X$SIZE_HINTS/ XSZHN 

RECORD /XSEVENT/ EVENT 

WINDOW_W = 600, WINDOW_H = 600, 


PARAMETER 
1 


B. 


ACK_W = 800, BACK_H = 800 
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Example 5-3 (Cont.) Allocating Colors for Exclusive Use 





aaa 


(eens 


aQaaQaa @oeo 


aan 


100 
100 


OFFSET X 
OFFSET _Y 


Initialize display id and screen id 


DPY = XSOPEN DISPLAY () 
SCREEN = XSDEFAULT_SCREEN_OF DISPLAY (DPY) 


STATUS = XSSYNCHRONIZE(DPY, 1, FUNC) 


Create the WINDOW window 


WINDOW _X 
WINDOW _Y 


(X$WIDTH_OF_SCREEN(SCREEN) - WINDOW_W) / 2 
(X$HEIGHT OF _SCREEN(SCREEN) - WINDOW_H) / 2 


DEPTH = XSDEFAULT DEPTH OF SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. X$M_CW_BACK_PIXEL 


XSWDA.X$L_SWDA_EVENT_ MASK = X$M_EXPOSURE .OR. X$SM_BUTTON_PRESS 
1 -OR. X$M_ EXPOSURE .OR. X$M_BUTTON_RELEASE .OR. 
1 XSM_STRUCTURE_NOTIFY 


XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 XSBLACK PIXEL OF SCREEN (SCREEN) 


WINDOW = X$CREATE_WINDOW(DPY, 

1 XSROOT WINDOW OF_SCREEN (SCREEN) , 

1 WINDOW _X, WINDOW_Y, WINDOW _W, WINDOW_H, 0, 

1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


Create graphics context 


GC = X$CREATE_GC(DPY, WINDOW, 0, 0) 
CALL X$SET_ FOREGROUND (DPY, GC, X$WHITE PIXEL_OF_SCREEN (SCREEN) ) 


Create the pixmap used for backing store 
PIXMAP = XS$CREATE PIXMAP(DPY, XSROOT_WINDOW (DPY, 
1 XSDEFAULT SCREEN (DPY)), BACK_W, BACK_H, DEPTH) 
CALL X$FILL_RECTANGLE(DPY, PIXMAP, GC, 0, 0, BACK_W, BACK_H) 


Create the initial colors for the wheel 


CALL CREATE COLORS (DPY, SCREEN, VISUAL, COLORS, CMAP, FULL_COUNT) 


Create the wheel 


CALL CREATE WHEEL(DPY, SCREEN, GC, PIXMAP, COLORS) 


Define the size and name of the WINDOW window 





(continued on next page) 
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Example 5-3 (Cont.) Allocating Colors for Exclusive Use 





XSZHN.X$L_SZHN_X = 212 
XSZHN.X$L_SZHN_Y = 132 
XSZHN.XS$L_SZHN WIDTH = 600 
XSZHN.XSL_SZHN HEIGHT = 600 
XSZHN.XS$L_SZHN FLAGS = X$M_P_POSITION .OR. X$M_P_SIZE 


CALL XS$SET_ NORMAL HINTS (DPY, WINDOW, XSZHN) 
CALL XSSTORE_NAME (DPY, WINDOW, 
1 ‘Color Wheel: Press MB1 to Rotate or Click MB2 to Exit.’) 


Cc 
¢ Map the window 
c 

CALL XS$MAP_WINDOW (DPY, WINDOW) 
C 
Cc Handle events 
Cc 

DO WHILE (.TRUE.) 

CALL X$NEXT_EVENT (DPY, EVENT) 

Cc 
Cc 


IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 
© CALL X$COPY_AREA(DPY, PIXMAP, WINDOW, GC, 


at OFFSET_X + EVENT. EVNT_EXPOSE.X$L_EXEV_X, 
1 OFFSET Y + EVENT.EVNT_EXPOSE.X$L_EXEV_Y, 
1 EVENT .EVNT_EXPOSE.X$L_EXEV_WIDTH, 
cl EVENT .EVNT_EXPOSE.X$L_EXEV_ HEIGHT, 
a EVENT. EVNT_EXPOSE.X$L_EXEV_X, 
1 EVENT.EVNT_EXPOSE.X$L_EXEV_Y) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 
BUTTON _IS DOWN = 1 
IF (BUTTON IS DOWN .EQ. 1) THEN 
CALL CHANGE COLORS (DPY, CMAP, COLORS, FULL_COUNT) 
END IF 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT .EVNT_BUTTON.X$L_BTEV BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT($VAL(1)) 
END IF 
IF (EVENT.EVNT_TYPE .£Q. X$C_BUTTON RELEASE) THEN 
BUTTON IS DOWN = 0 
END IF 
6 IF (EVENT.EVNT_TYPE .EQ. X$C_CONFIGURE_NOTIFY) THEN 
OFFSET _X = 
1 (BACK_W - EVENT .EVNT_CONFIGURE.X$L_CFEV_WIDTH) /2 
OFFSET Y = 
1 (BACK_H - EVENT.EVNT_CONFIGURE.X$L_CFEV_HEIGHT) /2 
END IF 
END DO 
END 


CREATE COLORS SUBROUTINE 


Ocroce 


SUBROUTINE CREATE COLORS (DISP, SCRN, VISU, CLRS, MAP, FC) 





(continued on next page) 
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Example 5-3 (Cont.) Allocating Colors for Exclusive Use 


INCLUDE ‘’SYSS$LIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, MAP, FC 
INTEGER*4 PIXELS (128) 
INTEGER*4 CONTIG, STATUS 
INTEGER*4 PLANE MASKS (128) 


RECORD /X$VISUAL/ VISU 
RECORD /X$COLOR/ CLRS (128) 


IF (VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_COLOR .OR. 
1  VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT COLOR) THEN 
‘6 MAP = X$DEFAULT_COLORMAP_OF_SCREEN (SCRN) 
FC = X$DISPLAY CELLS(DISP, X$DEFAULT_SCREEN (DISP) ) 
IF (FC .GT. 128) THEN 


FC = 128 
END IF 
STATUS = XSALLOC_COLOR_CELLS(DISP, MAP, CONTIG, PLANE MASKS, 
1 0, PIXELS, FC) 


IF (STATUS .EQ. 0) THEN 
CALL SYSSEXIT(%SVAL (1) ) 


END IF 
CALL LOAD COLORMAP (DISP, MAP, CLRS, PIXELS, FC) 
ELSE 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
RETURN 
END 


LOAD COLORMAP SUBROUTINE 


@coca 


SUBROUTINE LOAD _COLORMAP (DIS, MP, COLR, PIXS, COUNT) 
INCLUDE ‘SYSSLIBRARY:DECWSXLIBDEF’ 


INTEGER*4 DIS, MP, COUNT 
INTEGER*4 PIXS (128) 
INTEGER*4 I, C, FLAGS 
INTEGER*2 J (2) 
EQUIVALENCE (C, J(1)) 
REAL*16 H, R, G, B 


RECORD /X$COLOR/ COLR (128) 


FLAGS = X$M_DO RED .OR. X$M_DO GREEN .OR. X$M_DO BLUE 
DO I = 1, COUNT 
COLR(I) .X$L_COLR_PIXEL 
COLR(I) .X$B_COLR_ FLAGS 
8) H = I * 360./(COUNT + 1.) 
CALL HLS TO RGB(H, .5, .5, R, G, B) 
C= R * 65535.0 
COLR(I) .X$W_COLR_RED = J(1) 
Cc =G * 65535.0 
COLR (I) .X$W_COLR_GREEN = J(1) 
C = B * 65535.0 
COLR(I) .X$W_COLR_BLUE = J(1) 
END DO 
CALL XSSTORE COLORS (DIS, MP, COLR, COUNT) 


PIXS (I) 
FLAGS 





(continued on next page) 
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aaa 


Oocro 


RETURN 
END 


HLS _TO_RGB SUBROUTINE 


SUBROUTINE HLS_TO_RGB(HUE, LGHT, SATUR, RD, GRN, BLU) 


REAL*16 VALUE 

REAL*16 HUE, LGHT, SATUR 
REAL*16 RD, GRN, BLU 
REAL*16 M1, M2 


IF (LGHT .LT. .05) THEN 
M2 = L * (1 + SATUR) 

ELSE 
M2 

END IF 

Ml = 2 * LGHT - M2 

IF (SATUR .EQ. 0) THEN 


LGHT + SATUR - (LGHT * SATUR) 


RD = LGHT 

GRN = LGHT 

BLU = LGHT 
ELSE 


RD = VALUE(M1, M2, (HUE + 120.)) 

GRN = VALUE(M1, M2, (HUE + 000.)) 

BLU = VALUE(M1, M2, (HUE - 120.)) 
END IF 


RETURN 
END 


CREATE WHEEL SUBROUTINE 


SUBROUTINE CREATE WHEEL(DISP, SCRN, GRAPH CON, PMAP, CLRS) 
INCLUDE ’ SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, SCRN, GRAPH CON, PMAP 
INTEGER*4 I, J, PIXEL 

INTEGER*4 X_CENT, Y_CENT 

REAL*16 X, Y, XCENT_F, YCENT_F 


RECORD /XSCOLOR/ CLRS (128) 
RECORD /X$POINT/ PGON (387) 


PARAMETER PMAP WIDTH = 800, PMAP_ HEIGHT = 800 
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(— omens! 


i 


X_CENT = PMAP_ WIDTH/2 

Y_CENT = PMAP_HEIGHT/2 

PGON (1) .X$W_GPNT_X = PMAP_ WIDTH 
PGON (1) .X$W_GPNT_Y = PMAP_HEIGHT/2 
I= 2 

DO WHILE (I .LT. 384) 


PGON(I) .X$W_GPNT_X = X_CENT 
PGON(I) .X$W_GPNT Y = Y_CENT 
I=I+3 

END DO 

ae 

PIXEL = 1 


DO WHILE (PIXEL .LT. 129) 
XCENT_F = X_CENT 
YCENT F = Y CENT 
X = COS ((QFLOAT (PIXEL) /128) *2*3.14159) 
Y = SIN((QFLOAT (PIXEL) /128) *2*3.14159) 
PGON(I + 1).X$W_GPNT_X = (X * XCENT_F) + X_CENT 
PGON(I + 1).X$W_GPNT_y = (Y¥ * YCENT_F) + Y_CENT 
PGON(I + 2).XS$W_GPNT_X = PGON(I + 1).xX$W_GPNT_X 
PGON(I + 2).X$W_GPNT_Y = PGON(I + 1) .X$W_GPNT_Y 
CALL X$SET_FOREGROUND (DISP, GRAPH_CON, CLRS{(I+1)/3) .X$L_COLR_PIXEL) 
CALL X$FILL_POLYGON(DISP, PMAP, GRAPH_CON, PGON(I-1), 3, 





1 X$C_CONVEX, X$C_COORD_MODE_ORIGIN) 
1 te 3 
PIXEL = PIXEL + 1 

END DO 

RETURN 

END 


CHANGE COLORS SUBROUTINE 


SUBROUTINE CHANGE COLORS (DISP, MAP, CLRS, CNT) 
INCLUDE ‘'SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DISP, MAP, CNT, PENDING 
INTEGER*4 I, TEMP 


RECORD /XSCOLOR/ CLRS (128) 


DO WHILE (XSPENDING(DISP) .EQ. 0) 
TEMP = CLRS(1).X$L_COLR_PIXEL 
I=1l 
DO WHILE (I .LT, CNT) 
CLRS (I) .X$L_COLR_PIXEL = CLRS(I + 1) .X$L_COLR_PIXEL 
I=I 41 
END DO 
CLRS (CNT) .X$L_COLR_PIXEL = TEMP 
CALL X$STORE_COLORS(DISP, MAP, CLRS(1), CNT) 
END DO 


RETURN 
END 





(continued on next page) 
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Example 5~3 (Cont.) Allocating Colors for Exclusive Use 


VALUE FUNCTION 


Aaa 


REAL*16 FUNCTION VALUE(N1, N2, HUE) 
REAL*16 Nl, N2, HUE, VAL 


IF (HUE .GT. 360.) THEN 
HUE = HUE - 360. 
END IF 
IF (HUE .LT. 0) THEN 
HUE = HUE + 360. 
END IF 
IF (HUE .LT. 60) THEN 
VAL = Ni + (N2 - N1) * HUE/6O. 
ELSE IF (HUE .LT. 180.) THEN 
VAL = N2 
ELSE IF (HUE .LT. 240) THEN 
VAL = N1 + (N2 - N1) * (240. - HUE) /60. 


ELSE 

VAL = N1 
END IF 
VALUE = VAL 
RETURN 
END 


@ The client uses a pixmap as a backing store for the color wheel. When 
a user reconfigures the color wheel window, the client copies the color 
wheel from the pixmap into the resized window. For information about 
creating and using pixmaps, see Chapter 7. 


@ After creating the pixmap for backing store, the client creates colors 
for the wheel and the wheel itself. For details about these subroutines, 
see callouts 8, 9, and 10. 


© When the user reconfigures the window, the server generates an 
expose event. In response to the event, the client copies the pixmap 
into the exposed area, which is calculated using the offset from the 
original to the new position of the window. For information about 
handling exposure events, see Chapter 9. 


@ The client calculates the offset from the original window position in 
response to a configure notify event. The server issues a configure 
notify event each time the user resizes the color wheel window. For 
information about handling configure notify events, see Chapter 9. 


®@ The client-defined CREATE_COLORS routine allocates color cells for 
the exclusive use and stores initial color values in the color map. 


© The client uses the default color map, specifying that only 128 color 
cells be allocated. After allocating color cells, the client calls the 
client-defined LOAD_COLORMAP routine to define color values. 


@ The LOAD COLORMAP routine defines 128 colors and stores them in 
the color map. 
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Colors are defined initially using the Hue, Light, Saturation (HLS) 
system. The values of color hues vary, while values for light and 
saturation remain constant. After a color has been defined using HLS, 
the color is converted into RGB values by the client-defined HLS_TO_ 
RGB routine. When all colors are defined, the client stores them in the 
color map by calling the client-defined STORE COLORS routine. 


The client-defined CREATE_WHEEL routine defines the wheel used to 
display colors and specifies initial color values. 


The wheel is composed of polygons. Each polygon is defined by three 
points, one in the center of the wheel and two at the circumference. 
After the initial polygon is specified, each polygon shares one point 
with the polygon previously defined, as Figure 5-5 illustrates. 


To define each point the client uses a point data structure, which is 
described in Chapter 6. After defining a polygon, the client fills it with 
a specified foreground color. 


The rotation of the color wheel is accomplished by changing values in 
the color map. As long as there are no pending events, and the user 
is pressing MB1, the client-defined CHANGE_COLORS routine shifts 
color values by one. 
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Figure 5-5 Polygons That Define the Color Wheel 





a Pixmap 
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When allocating colors from any shared color map, the client may exhaust 
the resources of the color map. In this case, Xlib provides a routine for 
copying the default color map entries into a new client-created color map. 


To create a new color map when the client exhausts the resources of a 
previously shared color map, use the COPY COLORMAP AND FREE 
routine. The routine creates a color map of the same visual type and 

for the same screen as the previously shared color map. The previously 
shared color map can be either the default color map or a client-created 
color map. The COPY COLORMAP AND FREE routine has the following 
format: 


X§$COPY_COLORMAP_AND_FREE (display, colormap_id) 


COPY COLORMAP AND FREE copies all allocated cells from the 
previously shared color map to the new color map, keeping color values 
intact. The new color map is created with the same value of the argument 
alloc as the previously shared color map and has the following effect on 
the new color map entries: 
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Value of alloc Effect 


x$c_alloc_all All entries are copied from the previously shared color map 
and are then freed to create writable map entries. 


x$c_alloc_none The entries moved are all pixels and planes that have been 
allocated using the following routines and that have not been 
freed since they were allocated: ALLOC COLOR, ALLOC 
NAMED COLOR, ALLOC COLOR CELLS, ALLOC COLOR 
PLANES. 


Storing Color Values 


After allocating color entries in the color map, store RGB values in the 
color map cells using the following method: 


1 Assign color values to the color data structure and set the X$B_COLR_ 
FLAGS member to indicate the values defined. 


2 Call the STORE COLOR routine to store one color, the STORE 
COLORS routine to store more than one color, or the STORE NAMED 
COLOR routine to store a named color. 


The STORE COLOR routine has the following format: 
X$STORE_COLOR (display, colormap_id, screen_def_return) 
The STORE COLORS routine has the following format: 


XSSTORE_COLORS (display, colormap_id, screen_defs_return, 
num_colors) 


The STORE NAMED COLOR routine has the following format: 


X$STORE_NAMED COLOR(display, colormap_id, color_name, 
pixel, flags) 





Freeing Color Resources 


To free storage allocated for client colors, call the FREE COLORS routine. 
FREE COLORS releases all storage allocated by the following color 
routines: ALLOC COLOR, ALLOC COLOR CELLS, ALLOC NAMED 
COLORS, ALLOC COLOR PLANES. 


To delete the association between the color map ID and the color map, use 
the FREE COLORMAP routine. FREE COLORMAP has no effect on the 
default color map of the screen. If the color map is an installed color map, 
FREE COLORMAP removes it. 
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5.6 Querying Color Map Entries 





Querying Color Map Entries 
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Xlib provides routines to return both the RGB values of the color map 
index and the name of a color. 


To query the RGB values of a specified pixel in the color map, use the 
QUERY COLOR routine. The value returned is the value passed in the 
pixel member of the color data structure. 


To query the RGB values of an array of pixel values, use the QUERY 
COLORS routine. The values returned are the values passed in the pixel 
member of the color data structure. 


To look up the values associated with a named color, use the LOOKUP 
COLOR routine. LOOKUP COLOR uses the specified color map to find out 
the values with respect to a specific screen. It returns both the exact RGB 
values and the closest RGB values supported by hardware. 


6 Drawing Graphics 


Xlib provides clients with routines that draw graphics into windows and 
pixmaps. This chapter describes how to create and manage graphics 
drawn into windows, including the following topics: 


¢ Drawing points, lines, rectangles, and arcs 

¢ Filling rectangles, polygons, and arcs 

¢ Copying graphics 

¢ Limiting graphics to a region of a window or pixmap 
¢ Clearing graphics from a window 


¢ Creating cursors 


Chapter 7 describes drawing graphics into pixmaps. 





6.1 Graphics Coordinates 


Xlib graphics coordinates define the position of graphics drawn in a 
window or pixmap. Coordinates are either relative to the origin of the 
window or pixmap in which the graphics object is drawn or relative to a 
previously drawn graphics object. 


Xlib graphics coordinates are similar to the coordinates that define window 
position. Xlib measures length along the x axis from the origin to the 
right. Xlib measures length along the y axis from the origin down. Xlib 
specifies coordinates in units of pixels. 


6.2 Using Graphics Routines Efficiently 


If clients use the same drawable and graphics context for each call, 

Xlib handles back to back calls of DRAW POINT, DRAW LINE, DRAW 
SEGMENT, DRAW RECTANGLE, FILL ARC, and FILL RECTANGLE in 
a batch. Batching increases efficiency by reducing the number of requests 
to the server. 


When drawing more than a single point, line, rectangle, or arc, clients 
can also increase efficiency by using routines that draw or fill multiple 
graphics (DRAW POINTS, DRAW LINES, DRAW SEGMENTS, DRAW 
RECTANGLES, DRAW ARCS, FILL ARCS, and FILL RECTANGLES). 
Clipping negatively affects efficiency. Consequently, clients should ensure 
that graphics they draw to a window or pixmap are within the boundary 
of the drawable. Drawing outside the window or pixmap decreases 
performance. Clients should also ensure that windows into which they 
are drawing graphics are not occluded. 
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The most efficient method for clearing multiple areas is using the FILL 
RECTANGLES routine. By using the FILL RECTANGLES routine, clients 
can increase server performance. For information about using FILL 
RECTANGLES to clear areas, see Section 6.6.1. 





Drawing Points and Lines 


Drawing Points 


Xlib includes routines that draw points and lines. When clients draw 
more than one point or line, performance is most efficient if they use Xlib 
routines that draw multiple points or lines rather than calling single point 
and line-drawing routines many times. 


This section describes using routines that draw both single and multiple 
points and lines. 


To draw a single point, use the DRAW POINT routine, specifying x and y 
coordinates, as in the following: 


PARAMETER X = 100, Y = 100 


CALL XSDRAW_POINT(DPY, WINDOW, GC, X, Y) 
If drawing more than one point, use the following method: 
1 Define an array of point data structures. 


2 Call the DRAW POINTS routine, specifying the array that defines the 
points, the number of points the server is to draw, and the coordinate 
system the server is to use. The server draws the points in the order 
specified by the array. 


Xlib includes the point data structure to enable clients to define an array 
of points easily. Figure 6—1 illustrates the data structure. 


Figure 6-1 Point Data Structure 


| x$w_gpnt_y | x$w_gpnt_x | 0 
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Table 6-1 describes the members of the data structure. 


Table 6-1 Point Data Structure Members 


Member Name Contents 
X$W_GPNT_X Defines the x value of the coordinate of a point 
X$W_GPNT_Y Defines the y value of the coordinate of a point 


Drawing Graphics 
6.3 Drawing Points and Lines 


The server determines the location of points according to the following: 


¢ If the client specifies the constant x$c_coord_mode_origin, the 
server defines all points in the array relative to the origin of the 
drawable. 


¢ If the client specifies the constant x$c_coord_mode_previous, the 
server defines the coordinates of the first point in the array relative 
to the origin of the drawable and the coordinates of each subsequent 
point relative to the point preceding it in the array. 


The server refers to the following members of the GC data structure to 
define the characteristics of points it draws: 


Function Plane mask 
Foreground Subwindow mode 
Clip x origin Clip y origin 

Clip mask 


Chapter 4 describes GC data structure members. 


Example 6-1 uses the DRAW POINTS routine to draw a circle of points 
each time the user clicks MB1. 


Figure 6—2 illustrates sample output from the program. 


Example 6-1 Drawing Multiple Points 





aqaaQaqngaa 


aqaaa 


Create window WINDOW on display DPY, defined as follows: 


x = 100,y = 100 


600 
600 


GC refers to the graphics context 


PARAMETER 


POINT_CNT = 100, RADIUS = 50 


Handle events 


DO WHILE (.TRUE.) 


CALL XSNEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT TYPE .EQ. X$C_EXPOSE) THEN 


1 


1 


1 


CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


150, 25, 'To create points, click MBi’) 


CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


150, 50, 'Each click creates a new circle of points’) 


CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC, 


150, 75, ‘To exit, click MB2’) 


IF (EVENT. EVNT_TYPE .EQ. XSC_BUTTON PRESS .AND. 


1 


EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON1) THEN 





(continued on next page) 
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Example 6—1 (Cont.) Drawing Multiple Points 


x 
Y 


EVENT.EVNT_BUTTON.X$L_BTEV_X 
EVENT.EVNT_BUTTON.X$L_BTEV_Y 


Wit 


DO I = 1, POINT _CNT 
POINT_ARR(I) .X$W_GPNT_X 
POINT ARR(I) .X$W_GPNT_Y 


X + RADIUS * COS(FLOAT (TI) ) 
Y + RADIUS * SIN(FLOAT (I) ) 


tow 


END DO 
(3) CALL X$DRAW_POINTS(DPY, WINDOW, GC, POINT_ARR, POINT_CNT, 

1 X$C_COORD MODE ORIGIN) 
ENDIF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON_ PRESS .AND. 

1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN 

CALL SYSS$EXIT(SVAL (1) } 

END IF 

END DO 


@ After receiving notification that the server has mapped the window, 
the client writes three messages into the window. For information 
about using the DRAW IMAGE STRING routine, see Chapter 8. 


@ If the user clicks MB1, the client draws 50 points. If the user clicks 
MB2, the client exits from the system. The client determines which 
button the user clicked by referring to the button member of the 
button event data structure. For more information about the button 
event data structure, see Chapter 9. 


© The DRAW POINTS routine has the following format: 


XSDRAW_POINTS (display, drawable id, gc_id, points, 
num_points, point_mode) 


The point_mode argument specifies whether coordinates are relative 
to the origin of the drawable or to the previous point in the array. 


Drawing Graphics 
6.3 Drawing Points and Lines 


Figure 6-2 Circles of Points Created Using the DRAW POINTS Routine 


Drawing Multiple Points 


To create points, click MB1. 
Each click creates a new circle of points. 
To exit, click MB2. 
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6.3.2 Drawing Lines and Line Segments 


Xlib includes routines that draw single lines, multiple lines, and line 
segments. To draw a single line, use the DRAW LINE routine, specifying 
beginning and ending points, as in the following: 

PARAMETER X1 = 100, Y¥1 = 100, 

1 X2 = 200, Y2 = 200 


CALL X$DRAW_LINE(DISPLAY, WINDOW, GC, X1, Y1, X2, Y2) 
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To draw multiple lines, use the following method: 


1 Define an array of points using the point data structure described in 
Section 6.3.1 to specify beginning and ending line points. The server 
interprets pairs of array elements as beginning and ending points. For 
example, if the array that defines the beginning point is point|:], the 
server reads point|i + 1] as the corresponding ending point. 


2 Call the DRAW LINES routine, specifying the following: 
¢ The array that defines the points. 
¢ The number of points that define the line. 


¢ The coordinate system the server uses to locate the points. The 
server draws the lines in the order specified by the array. 


Clients can specify either the x$c_coord_mode_origin or the 
x$c_coord_mode_previous constant to indicate how the server 
determines the location of beginning and ending points. The server uses 
the methods described in Section 6.3.1. 


The server draws lines in the order the client has defined them in the 
point data structure. Lines join correctly at all intermediate points. If 
the first and last points coincide, the first and last line also join correctly. 
For any given line, the server draws pixels only once. The server draws 
intersecting pixels multiple times if zero-width lines intersect; it draws 
intersecting pixels of wider lines only once. 


Example 6-2 uses the DRAW LINES routine to draw a star when the 
server notifies the client that the window is mapped. 


Example 6-2 Drawing Multiple Lines 





aqaaanaana 


Qaaa 
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Create window WINDOW on display DPY, defined as follows: 


Position: x = 100,y = 100 
Width = 600 
Height = 600 


GC refers to the graphics context 


PARAMETER POINT CNT = 100, RADIUS = 50 


Handle events 
DO WHILE (.TRUE.) 


CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_ IMAGE STRING(DPY, WINDOW, GC, 


1 150, 25, ‘To create a Star, click MBi.’) 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ’To exit, click MB2.’) 
END IF 


(continued on next page) 
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2) 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS 
EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON 


1 


POINT_ARR (1) 
POINT _ARR(1) 
POINT ARR (2) 
POINT ARR (2) 
POINT _ARR (3) 
POINT ARR (3) 
POINT _ARR (4) 
POINT ARR (4) 
POINT ARR(5) 
POINT ARR (5) 
POINT_ARR (6) 
POINT_ARR (6) 


.X$W_GPNT_X 
-X$W_GPNT_Y 
.XSW_GPNT_X 
.XSW_GPNT_Y 
.XSW_GPNT_X 
.X$W_GPNT_Y 
.XSW_GPNT_X 
-X$W_GPNT_Y 
.XSW_GPNT_X 
.XSW_GPNT_Y 
.XSW_GPNT_X 
.XSW_GPNT_Y 


oink ft tt t dod t a tt 


75 

500 
300 
100 
525 
500 
50 

225 
575 
225 
75 

500 
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-AND. 
-EQ. X$C_BUTTON1) THEN 


CALL XSDRAW_LINES (DPY, WINDOW, GC, POINT_ARR, POINTS, 


1 


ENDIF 


X$C_COORD_MODE_ORIGIN) 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON2) THEN 


CALL SYSSEXIT (%VAL (1) ) 


END IF 


END DO 





@ The program uses point data structures to define beginning and ending 
points of lines. 


The call to draw lines refers to a graphics context (GC), which the 
client has previously defined, and an array of point data structures. 
The constant x$c_coord_mode_origin indicates that all points are 
relative to the origin of WINDOW (100, 100). 


Figure 6-3 illustrates the resulting output. 


6-7 


Drawing Graphics 
6.3 Drawing Points and Lines 


Figure 6-3 Star Created Using the DRAW LINES Routine 


Drawing Multiple Lines 


To create a star, click MB1. 
To exit, click MB2. 
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Use the DRAW SEGMENTS routine to draw multiple, unconnected lines, 
defining an array of segments in the segment data structure. Figure 6-4 
illustrates the data structure. 


Figure 6-4 Segment Data Structure 






x$w_gseg_y1 x$w_gseg_x1 
x$w_gseg_y2 x$w_gseg_x2 
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Table 6—2 describes the members of the data structure. 


Table 6-2 Segment Data Structure Members 


Member Name Contents 

X$W_GSEG_X1 The x value of the coordinate that specifies one endpoint of 
the segment 

X$W_GSEG_Y1 The y value of the coordinate that specifies one endpoint of 
the segment 

X$W_GSEG_X2 The x value of the coordinate that specifies the other endpoint 
of the segment 

X$W_GSEG_Y2 The y value of the coordinate that specifies the other endpoint 


of the segment 


DRAW SEGMENTS functions like the DRAW LINES routine, except the 
routine does not use the coordinate mode. 


The DRAW LINE and DRAW SEGMENTS routines refer to all but the join 
style, fill rule, arc mode, and font members of the GC data structure to 
define the characteristics of lines. The DRAW LINES routine refers to all 
but the fill rule, arc mode, and font members of the data structure. 


Chapter 4 describes the GC data structure. 


6.4 Drawing Rectangles and Arcs 


As with routines that draw points and lines, Xlib provides clients the 
choice of drawing either single or multiple rectangles and arcs. If a client 
is drawing more than one rectangle or arc, use the multiple-drawing 
routines for most efficiency. 


6.4.1. Drawing Rectangles 


To draw a single rectangle, use the DRAW RECTANGLE routine, 
specifying the coordinates of the upper left corner and the dimensions 
of the rectangle, as in the following: 


PARAMETER X 
1 WIDTH 


50, Y = 100, 
25, LENGTH = 50 


tod 


CALL XSDRAW_RECTANGLE (DISPLAY, WINDOW, GC, X, Y¥, WIDTH, LENGTH) 


Figure 6-5 illustrates how Xlib interprets coordinate and dimension 
parameters. The z and y coordinates are relative to the origin of the 
drawable. 
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Figure 6-5 Rectangle Coordinates and Dimensions 
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To draw multiple rectangles, use the following method: 
1 Define an array of rectangles using the rectangle data structure. 


2 Call the DRAW RECTANGLES routine, specifying the array that 
defines rectangle origin, width, and height, and the number of array 
elements. 


The server draws each rectangle as shown in Figure 6-6. 


Figure 6-6 Rectangle Drawing 


Path of lines drawn 
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For a specified rectangle, the server draws each pixel only once. If 
rectangles intersect, the server draws intersecting pixels multiple times. 


Xlib includes the rectangle data structure to enable clients to define an 
array of rectangles easily. Figure 6-7 illustrates the data structure. 


Figure 6-7 Rectangle Data Structure 









: 
x$w_grec_height x$w_grec_width 4 





Table 6—3 describes the members of the data structure. 


Table 6-3 Rectangle Data Structure Members 


Member Name Contents 

X$W_GREC_X Defines the x value of the rectangle origin 
X$W_GREC_Y Defines the y value of the rectangle origin 
X$W_GREC_WIDTH Defines the width of the rectangle 
X$W_GREC_HEIGHT Defines the height of the rectangle 


When drawing either single or multiple rectangles, the server refers 
to the following members of the GC data structure to define rectangle 


characteristics: 

Function Plane mask 
Foreground Background 

Line width Line style 

Join style Fill style 

Tile Stipple 

Tile/stipple x origin Tile/stipple y origin 
Subwindow mode Clip x origin 

Clip y origin Clip mask 

Dash offset Dashes 


Chapter 4 describes the GC data structure members. 


Example 6-3 illustrates using the DRAW RECTANGLES routine. 
Figure 6-8 shows the resulting output. 
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Example 6-3 Drawing Multiple Rectangles 


Create window WINDOW on display DPY, defined as follows: 
Position: x = 100,y = 100 
Width = 600 
Height = 600 

GC refers to the graphics context 


aAaaana 


PARAMETER POINT _CNT = 100, RADIUS = 50 


Handle events 


aaa 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT (DPY, EVENT) 


1] IF (EVENT.EVNT TYPE .EQ. X$C_EXPOSE) THEN 
CALL XSDRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 25, ‘To draw multiple rectangles, click MB1.’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ‘’To exit, click MB2.’) 
END IF 


Qe IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 


DO I = 1, REC_CNT 
REC_ARR(I) .X$W_GREC_X = STEP * I 
REC_ARR(I) .X$W_GREC_Y = STEP * I 
REC_ARR(I).X$W_GREC_WIDTH = STEP * 2 
REC_ARR(I) .X$W_GREC_HEIGHT = STEP * 3 

END DO 


{I 


13 CALL X$DRAW_RECTANGLES (DPY, WINDOW, GC, REC_ARR, REC_CNT) 
ENDIF 


IF (EVENT.EVNT_ TYPE .EQ. X$C_BUTTON_ PRESS .AND. 
1 EVENT. EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. XSC_BUTTON2) THEN 
CALL SYSSEXIT (%VAL (1) ) 


END IF 
END DO 





@ After receiving notification that the server has mapped the window, 
the client writes two messages into the window. For information about 
using the DRAW IMAGE STRING routine, see Chapter 8. 


@ If the user clicks MB1, the client draws rectangles defined in the 
initialization loop. If the user clicks MB2, the client exits the system. 
The client determines which button the user has clicked by referring 
to the button member of the button event data structure. For more 
information about the button event data structure, see Chapter 9. 


© The DRAW RECTANGLE routine has the following format: 


XSDRAW_RECTANGLES (display, drawable_id, gc_id, rectangles, 
num_rectangles) 
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Drawing Graphics 
6.4 Drawing Rectangles and Arcs 


Figure 6-8 Rectangles Drawn Using the DRAW RECTANGLES Routine 


Drawing Multiple Rectangles ail 


To draw multiple rectangles, click MB1. 


To exit, click MB2. 
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Xlib routines enable clients to draw either single or multiple arcs. To 
draw a single arc, use the DRAW ARC routine, specifying a rectangle that 
defines the boundaries of the arc and two angles that determine the start 
and extent of the arc, as in the following: 


PARAMETER X = 50, Y = 100, 
1 WIDTH = 25, LENGTH = 50, 
a: ANGLEL = 5760, ANGLE2 = 5760 


CALL XS$DRAW_ARC (DISPLAY, WINDOW, GC, X, Y, WIDTH, HEIGHT, 
1 ANGLE1, ANGLE2) 
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The server draws an arc within a rectangle. The client specifies the upper 
left corner of the rectangle, relative to the origin of the drawable. The 
center of the rectangle is the center of the arc. The width and height of 
the rectangle are the major and minor axes of the arc, respectively. 


Two angles specify the start and extent of the arc. The angles are signed 
integers in degrees scaled up by 64. For example, a client would specify a 
90 degree arc as 64+ 90 or 5760. The start of the arc is specified by the first 
angle, relative to the three o’clock position from the center of the rectangle. 
The extent of the arc is specified by the second angle, relative to the start 
of the arc. Positive integers indicate counterclockwise motion; negative 
integers indicate clockwise motion. 


Figure 6-9 illustrates the relationships among the rectangle, axes, and 
angles that specify the arc. 


Figure 6-9 Specifying an Arc 





Angle 2: 
Relative to 
X-Y Angle 1 
Coordinate 
Angle 1: 
Relative to Three 
O'clock Position 
Height Three O'clock 
Position 
Width 
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For an arc specified as [ 2, y, width, height, angle1, angle2], the origin of the 
major and minor axes is at [ « + width/2, y + height/2]. The infinitely 
thin path describing the entire arc intersects the horizontal axis at 

[ 2, y+ height/2] and [ x+ width, y + height/2] and the vertical axis at 

[ e+ width/2, yl and [ «+ width/2, y+ height]. These coordinates are not 
truncated to discrete coordinates if they are fractional. 


The path of the arc is defined as the ideal mathematical path. For a wide 
line of width w, the bounding outlines for filling are given by two infinitely 
thin paths consisting of all points whose perpendicular distance from the 
path of the circle or ellipse is equal to w/2. 
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For an ellipse defined as [ z, y, width, height, angle1, angle2], the angles 
must be specified in the skewed coordinate of the ellipse. The relationship 
between the coordinate system of the ellipse and that of a circle is specified 
using the following formula: 


skewed angle = atan(tan(normal angle) * width/height) + adjust 


The skewed angle and normal angle are expressed in radians (rather than 
in degrees scaled by 64) in the range [ 0, 2 « 7], where the atan returns a 
value in the range [ —1/2, 1/2]. The adjust is as follows: 


¢ 0 for normal-angle in the range [ 0, 1/2] 
¢ «for a normal angle in the range [ 1/2, 3 * 7/2] 


¢ 2. for a normal angle in the range [ 3 * r/2, 2 * 7] 


To draw multiple arcs, use the following method: 
1 Define an array of arc data structures. 


2 Call the DRAW ARCS routine, specifying the array that defines the 
arcs and the number of array elements. 


Figure 6-10 illustrates the arc data structure. 
Figure 6-10 Arc Data Structure 















: 
x$w_garc_height x$w_garc_width 4 
x$w_gare_angle2 x$w_garc_angle1 8 

Table 6—4 describes the members of the arc data structure. 

Table 6—4 Arc Data Structure Members 

Member Name Contents 

X$W_GARC_X Defines the x-coordinate value of the rectangle in which 
the server draws the arc 

X$W_GARC_Y Defines the y-coordinate value of the rectangle in which 
the server draws the arc 

X$W_GARC_WIDTH Defines the major axis of the arc 

X$W_GARC_HEIGHT Defines the minor axis of the arc 


(continued on next page) 
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Table 6—4 (Cont.) Arc Data Structure Members 





Member Name Contents 

X$W_GARC_ANGLE1 Defines the starting point of the arc relative to the 
3-o’clock position from the center of the rectangle 

X$W_GARC_ANGLE2 Defines the extent of the arc relative to the starting point 


When drawing either single or multiple arcs, the server refers to the 
following members of the GC data structure to define arc characteristics: 


Function Plane mask 
Foreground Background 

Line width Line style 

Join style Cap style 

Fill style Tile 

Tile/stipple x origin Tile/stipple y origin 
Clip x origin Clip y origin 

Clip mask Dash offset 
Dashes Stipple 


Subwindow mode 
Chapter 4 describes the GC data structure members. 


If the last point in one arc coincides with the first point in the following 
arc, the two arcs join. If the first point in the first arc coincides with the 
last point in the last arc, the two arcs join. 


If two arcs join, the line width is greater than zero, and the arcs intersect, 
the server draws all pixels only once. Otherwise, it may draw intersecting 
pixels multiple times. 


Example 6-4 illustrates using the DRAW ARCS routine. 
Example 6—4 Drawing Multiple Arcs 


Cc Create window WINDOW on display DPY, defined as follows: 
Cc Position: x = 100,y = 100 

Cc Width = 600 

Cc Height = 600 

Cc GC refers to the graphics context 


PARAMETER ARC_CNT = 16, RADIUS = 50, 
1 INNER_RADIUS = 20 


Handle events 


aaa 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 


(continued on next page) 
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Example 6-4 (Cont.) Drawing Multiple Arcs 





IF (EVENT.EVNT_ TYPE .EQ. X$C_EXPOSE) THEN 
CALL XSDRAW_IMAGE STRING(DPY, WINDOW, GC, 


BP 150, 25, ‘To create arcs, click MB1.’) 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ’Each click creates a new circle of arcs.’) 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, ‘To exit, click MB2.’) 
END IF 
IF (EVENT .EVNT_TYPE EQ. X$C_BUTTON_PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON1) THEN 
1] X = EVENT.EVNT_BUTTON.X$L_BTEV_X 


Y = EVENT.EVNT_BUTTON.XSL_ BTEV_Y 


DO I = 1, ARC_CNT 
ARC_ARR(I) .X$W_GARC_ANGLE1 = (64 * 360)/ARC_CNT * I 
ARC_ARR (I) .X$W_GARC_ANGLE2 = (64 * 360)/ARC_CNT * 3 
ARC_ARR(I) .X$W_GARC_WIDTH = RADIUS * 2 
ARC_ARR(I) .X$W_GARC_HEIGHT = RADIUS * 2 
ARC_ARR(I) .X$W_GARC_X = X - RADIUS + 


1 SIN(2*3.14159/ARC_CNT*I) * INNER RADIUS 
ARC_ARR (I) .X$W_GARC_Y = Y ~ RADIUS + 
1 COS (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
END DO 
e CALL X$DRAW_ARCS(DPY, WINDOW, GC, ARC_ARR, ARC_CNT) 
ENDIF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
END DO 





@ The x and y variables specify the upper left corner of the rectangle that 
defines the boundary of the arc. The client determines the rectangle 
coordinates by taking the values of the x and y arguments from the 
button event data structure. Because these values indicate the position 
of the cursor when the user clicks the mouse button, the server draws 
the arcs relative to the position of the cursor. For more information 
about the button event data structure, see Chapter 9. 


@ The DRAW ARCS routine has the following format: 


X$DRAW_ARCS (display, drawable_id,gc_id,arcs,num_arcs) 


Figure 6-11 illustrates the resulting output. 
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Figure 6-11 Multiple Arcs Drawn Using the DRAW ARCS Routine 


Drawing Multiple Arcs 


To create arcs, click MB1. 
Each click creates a new circle of arcs. 
To exit, click MB2. 
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6.5 Filling Areas 


This section describes using Xlib routines to fill single rectangles, arcs, 
and polygons, and multiple rectangles and arcs. 


6.5.1.‘ Filling Rectangles and Arcs 


The FILL RECTANGLE, FILL RECTANGLES, FILL ARC, and FILL 
ARCS routines create single and multiple rectangles or arcs and fill them 
using the fill style the client specifies in a graphics context data structure. 


The method of calling the fill routines is identical to that for drawing 
rectangles and arcs. For example, to create rectangles filled solidly with 
foreground color in Example 6-3, the client needs only to call the FILL 
RECTANGLES routine instead of DRAW RECTANGLES. The default 
value of the GC data structure fill style member is solid. If the client were 
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to specify a tile or stipple for filling the rectangles, the client would have 
to change the graphics context used by the FILL RECTANGLES routine. 


The server refers to the following members of the GC data structure to 
define characteristics of the rectangles and arcs it fills: 


Function Plane mask 
Foreground Background 

Fill style Tile 

Stipple Subwindow mode 
Tile/stipple x origin Tile/stipple y origin 
Clip x origin Clip y origin 

Clip mask 


Additionally, the server refers to the arc mode member if filling arcs. 


For information about using graphics context, see Chapter 4. 


6.5.2 ‘Filling a Polygon 
To fill a polygon, use the following method: 
1 Define an array of point data structures. 


2 Call the FILL POLYGON routine, specifying the array that defines the 
points of the polygon, the number of points the server is to draw, the 
shape of the polygon, and the coordinate system the server is to use. 
The server draws the points in the order specified by the array. 


See Figure 6-1 for an illustration of the point data structure. 


To improve performance, clients can specify whether the shape of the 
polygon is complex, convex, or nonconvex, as follows: 


¢ Specify the constant x$c_complex as the shape argument if the path 
that draws the polygon may intersect itself. 


¢ Specify the constant x$c_convex if the path that draws the shape is 
wholly convex. If a client specifies x$e_convex for a path that is not 
convex, the results are undefined. 


¢ Specify the constant x$c_nonconvex as the shape argument if the 
path does not intersect itself, but the shape is not wholly convex. Ifa 
client specifies x$c_nonconvex for a path that intersects itself, the 
results are undefined. 


When filling the polygon, the server draws each pixel only once. 
The server determines the location of points as follows: 


e If the client specifies the constant x$c_coord_mode_origin, the 
server defines all points in the array relative to the origin of the 
drawable. 
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¢ If the client specifies the constant x$c_coord_mode_previous, the 
server defines the coordinates of the first point in the array relative 
to the origin of the drawable and the coordinates of each subsequent 
point relative to the point preceding it in the array. 


If the last point does not coincide with the first point, the server closes the 
polygon automatically. 


The server refers to the following members of the GC data structure to 
define the characteristics of the polygon it fills: 


Function Plane mask 
Foreground Fill style 

Fill rule (if polygon is complex) Tile 

Tile/stipple x origin Tile/stipple y origin 
Clip x origin Clip y origin 
Subwindow mode Clip mask 

Stipple Background 


Chapter 4 describes GC data structure members. 


Example 6—5 uses the FILL POLYGON routine to draw and fill the star 
created in Example 6-2. 


Example 6-5 Filling a Polygon 


Create window WINDOW on display DPY, defined as follows: 
Position: x = 100,y = 100 
Width = 600 
Height = 600 

GC refers to the graphics context 


+) aAaaana 


RECORD /X$POINT/ PT_ARR(6) 
PT_ARR(1) .X$W_GPNT_X = 75 


PT _ARR(1).X$W_GPNT_Y = 500 
PT _ARR(2).X$W_GPNT_X = 300 
PT ARR(2).X$W_GPNT_Y = 100 
PT ARR(3).X$W_GPNT X = 525 
PT ARR(3).X$W_GPNT y = 500 
PT _ARR(4).X$W_GPNT X = 50 

PT _ARR(4).X$W_GPNT Y = 225 
PT ARR(5).X$W_GPNT X = 575 
PT ARR(5).XSW_GPNT Y = 225 
PT _ARR(6).X$W_GPNT_X = 75 

PT _ARR(6).X$W_GPNT_Y = 500 





(continued on next page) 
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Example 6-5 (Cont.) Filling a Polygon 


c 
c 
C 


Handle events 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


1 150, 25, 'To create a filled polygon, click MB1’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ‘To exit, click MB2’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .~ AND. 
1 EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 
CALL XSFILL POLYGON (DPY, WINDOW, GC, PT_ARR, 6, X$C_COMPLEX, 
1 X$C_COORD_MODE ORIGIN) 
ENDIF 





@ Use an array of point data structures to specify the points that define 
the polygon. 


@ The call to fill the polygon refers to a graphics context (GC), which the 
client has previously defined, and an array of point data structures. 
The constant x$c_complex indicates that the path of the line that 
draws the polygon intersects itself. The constant x$c_coord_mode_ 
origin indicates that all points are relative to the origin of WINDOW 
(100,100). 


Figure 6-12 illustrates the resulting output. 
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Figure 6-12 Filled Star Created Using the FILL. POLYGON Routine 


lat lilipre mcm axel hcecels) 


To create a filled polygon, click MB1. 


To exit, click MB2. 
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6.6 Clearing and Copying Areas 


Xlib includes routines that enable clients to clear or copy a specified area 
of a drawable. Because pixmaps do not have defined backgrounds, clients 
clearing an area of a pixmap must use the FILL RECTANGLE routine 
described in Section 6.5.1. For more information about pixmaps, see 
Chapter 7. 


This section describes how to clear windows and copy areas of windows 
and pixmaps. 
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6.6.1 Clearing Window Areas 


To clear an area of a window, use the CLEAR AREA or CLEAR WINDOW 
routine. The CLEAR AREA routine clears a specified area and generates 
an exposure event, if the client directs the server to do so. 


The CLEAR WINDOW routine clears the entire area of the specified 
window. If the window has a defined background tile, the window is 
retiled. If the window has no defined background, the server does not 
change the window contents. 


Example 6-6 illustrates clearing a window. 


Example 6-6 Clearing a Window 


IF (EVENT. EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 


1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN 
X = EVENT.EVNT_BUTTON.X$L_BTEV_X 
Y = EVENT.EVNT BUTTON.X$L_BTEV_Y 
DO I = 1, ARC_CNT 
ARC_ARR(I).X$W_GARC_ANGLE1 = (64 * 360)/ARC_CNT * I 
ARC_ARR(I).X$W_GARC_ANGLE2 = (64 * 360)/ARC_CNT * 3 
ARC_ARR(I).X$W_GARC_WIDTH = RADIUS * 2 
ARC_ARR(I).X$W_GARC_ HEIGHT = RADIUS * 2 
ARC_ARR(I) .X$W_GARC_X = X - RADIUS + 
ak SIN (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
ARC_ARR (I) .X$W_GARC_Y = Y - RADIUS + 
al COS (2*3.14159/ARC_CNT*I) * INNER RADIUS 
END DO 
CALL X$DRAW_ARCS(DPY, WINDOW, GC, ARC_ARR, ARC_CNT) 
ENDIF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN 


CALL SYSSEXIT(%VAL(1) ) 


END IF 


IF (EVENT.EVNT TYPE .EQ. XSC_BUTTON PRESS .AND. 
1 EVENT.EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON3) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW) 


END IF 
END DO 


The example modifies Example 6-4 to clear the window when the user 
clicks MB3. 


If clearing multiple areas, using the FILL RECTANGLES routine is faster 
than using the CLEAR WINDOW or CLEAR AREA routine. To clear 
multiple areas on a monochrome screen, first set the function member of 
the GC data structure to the value specified by the constant 
X$C_GX_CLEAR. Then call the FILL RECTANGLES routine. If the 
screen is a color type, set the value of the background to the background of 
the window before calling FILL RECTANGLES. 
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6.6.2 Copying Areas of Windows and Pixmaps 


Xlib includes the COPY AREA and COPY PLANE routines to enable 
clients to copy a rectangular area defined on one window or pixmap (the 
source) to an area of another window or pixmap (the destination). COPY 
AREA copies areas between drawables of the same root and depth. COPY 
PLANE copies a single bit plane of the specified drawable to another 
drawable, regardless of their depths. The bit plane is treated as a stipple 
with a fill style of x$c_fill_opaque_stippled. Both drawables must have 
the same root window. 


The server refers to the following members of the GC data structure when 
copying areas and planes: 


Function Plane mask 
Clip x origin Clip y origin 
Subwindow mode Clip mask 


Graphics exposures 


If the client calls COPY AREA or COPY PLANE, the server also refers to 
the graphics exposures member of the GC data structure. If the client calls 
the COPY PLANE routine, the server additionally refers to the foreground 
and background members. 





6.7 Defining Regions 


A region is an arbitrarily defined area within which graphics drawing is 
clipped. In other words, clipping regions are portions of either windows or 
pixmaps in which clients can restrict output. As Chapter 4 notes, the SET 
CLIP MASK, SET CLIP ORIGIN, and SET CLIP RECTANGLES routines 
define clipping regions. Xlib provides other, more convenient, routines that 
enable clients to define regions and associate them with drawables without 
having to change graphics context values directly. 


This section describes how to create and manage clipping using Xlib region 
routines. 


6.7.1. Creating Regions 
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Xlib includes the CREATE REGION and POLYGON REGION routines for 
creating regions. CREATE REGION creates an empty region. POLYGON 
REGION creates a region defined by an array of points. 


Example 6—7 illustrates using POLYGON REGION to create a star-shaped 
region. Using the DRAW ARCS routine of Example 6-4, the program 
limits arc drawing to the star region. 
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Example 6-7 Defining a Region Using the POLYGON REGION Routine 


Cc Create window WINDOW on display DPY, defined as follows: 
c Position: x = 100,y = 100 
C Width = 600 
c Height = 600 
Cc GC refers to the graphics context 
INTEGER*4 STAR_REGION 
PARAMETER WINDOW_W = 600, WINDOW_H = 600, 
1 ARC_CNT = 16, RADIUS = 50, 
1 INNER_RADIUS = 20, NUM_POINTS = 6 
RECORD /XSARC/ ARC_ARR(ARC_CNT) 
RECORD /XSPOINT/ POINT_ARR(NUM_POINTS) 
0 POINT _ARR(1).XSW_GPNT_X = 75 
POINT ARR(1).X$W_GPNT_Y = 500 
POINT ARR(2).X$W_GPNT X = 300 
POINT ARR(2).X$W_GPNT_Y = 100 
POINT ARR(3).XSW_GPNT X = 525 
POINT_ARR(3) .X$W_GPNT_Y = 500 
POINT ARR(4).X$W_GPNT_X = 50 
POINT ARR(4) .X$W_GPNT_Y = 225 
POINT ARR(5).X$W_GPNT_X = 575 
POINT ARR(5).XSW_GPNT Y = 225 
POINT ARR(6) .X$W_GPNT_X = 75 
POINT _ARR(6).X$W_GPNT_ y = 500 
e STAR_REGION = X$POLYGON_REGION (POINT ARR, NUM POINTS, 
1 XSC_WINDING_RULE) 
Cc 
Cc Handle events 
Cc 


DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT TYPE .EQ. XS$C_EXPOSE) THEN 
CALL XSDRAW_IMAGE_ STRING (DPY, WINDOW, GC, 
1 150, 25, ‘To create arcs, click MB1.’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 


1 150, 50, ‘Each click creates a new circle of arcs.’) 
CALL XSDRAW_IMAGE_STRING (DPY, WINDOW, GC, 
1 150, 75, ’To exit, click MB2.’) 
END IF 
IF (EVENT.EVNT_ TYPE .EQ. X$C_BUTTON_PRESS ~AND. 
1 EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON EQ. X$C_BUTTON1) THEN 
X = EVENT.EVNT_BUTTON.X$L_BTEV_X 


XY 


EVENT .EVNT_BUTTON.X$L_BTEV_Y 





(continued on next page) 
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Example 6-7 (Cont.) Defining a Region Using the POLYGON REGION Routine 


© CALL X$SET_REGION(DPY, GC, STAR_REGION) 
DO I = 1, ARC_CNT 


ARC_ARR(I).X$W_GARC_ANGLE1 = (64 * 360)/ARC_CNT * I 
ARC_ARR(I).X$W_GARC_ANGLE2 = (64 * 360)/ARC_CNT * 3 
ARC_ARR(I) .X$W_GARC_WIDTH = RADIUS * 2 

ARC_ARR(I) .X$W_GARC_HEIGHT = RADIUS * 2 
ARC_ARR(I).X$W_GARC_X = X - RADIUS + 


re SIN (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
ARC_ARR(I).X$W_GARC_Y = Y - RADIUS + 
1 COS (2*3.14159/ARC_CNT*I) * INNER_RADIUS 
END DO 
CALL X$DRAW_ARCS(DPY, WINDOW, GC, ARC_ARR, ARC_CNT) 
ENDIF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 
1 EVENT. EVNT_BUTTON.X$L_BTEV_ BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT (%VAL (1) ) 
END IF 
END DO 





@ Define an array of point data structures to define the clipping region. 


@ Define the clipping region. Note that defining the region does not 
associate it with a graphics context. 


Fill rule can be either even odd rule or winding rule. For more 
information about fill rule, see Chapter 4. 


© Associate the region with a graphics context. The association sets 
fields in the specified GC data structure that control clipping. 
Drawables that refer to the GC data structure have output clipped 
to the region. 


Figure 6-13 illustrates sample output from the program. 
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Figure 6-13 Arcs Drawn Within a Region 


Drawing Multiple Arcs in a Region 


To create arcs, click MB1. 
Each click creates a new circle of arcs. 
To exit, click MB2. 
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6.7.2 Managing Regions 


Xlib includes routines that enable clients to do the following: 
* Move and shrink a region 


¢ Compute the intersection, union, and results of two regions 


¢ Determine if regions are empty or equal 
¢ Locate a point or rectangle within a region 


Table 6—5 lists and describes Xlib routines that manage regions. 
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Table 6-5 Routines for Managing Regions 


Routine Description 


Moving and Shrinking 


OFFSET REGION Moves a region a specified amount 

SHRINK REGION Reduces a region a specified amount 
Computing 

INTERSECT REGION Computes the intersection of two regions 
UNION REGION Computes the union of two regions 

SUBTRACT REGION Subtracts two regions 

XOR REGION Calculates the difference between the union and 


intersection of two regions 


Determining if Regions are Empty or Equal 


EMPTY REGION Determines if a region is empty 
EQUAL REGION Determines if two regions have the same offset, size, 
and shape 


Locating a Point or Rectangle Within a Region 


POINT IN REGION Determines if a point is within a region 
RECT IN REGION Determines if a rectangle is within a region 


Example 6-8 illustrates creating a region from the intersection of two 
others. 


Example 6-8 Defining the Intersection of Two Regions 





aaAaaaAaAanN 


Create window WINDOW on display DPY, defined as 


follows: 


Position: 
600 
600 


Width = 
Height 


x = 100,y = 100 


GC refers to the graphics context 


INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 
INTEGER* 4 


PIXMAP 1 
PIXMAP 2 
PIXMAP 3 
REGION 1 
REGION 2 
REGION_3 


RECORD /X$POINT/ PT_ARR1 (4) 
RECORD /X$POINT/ PT_ARR2 (4) 
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Example 6-8 (Cont.) Defining the Intersection of Two Regions 





aaa 
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PT ARRi(1).X$W_GPNT_X = 200 
PT ARR1(1).X$W_GPNT_Y = 100 
PT ARR1(2).X$W_GPNT_X = 50 
PT ARR1(2).X$W_GPNT Y = 300 
PT_ARR1 (3) .X$W_GPNT_X = 200 
PT_ARR1(3).X$W_GPNT_Y = 500 
PT ARR1(4).X$W_GPNT X = 350 
PT ARR1(4).X$W_GPNT Y = 300 
PT ARR2(1).X$W_GPNT_X = 400 
PT ARR2(1).X$W_GPNT Y = 100 
PT ARR2(2).X$W_GPNT X = 250 
PT ARR2(2).X$W_GPNT_Y = 300 
PT ARR2(3).X$W_GPNT X = 400 
PT ARR2(3).X$W_GPNT Y = 500 
PT ARR2(4).X$W_GPNT X = 550 
PT ARR2(4).XSW_GPNT_Y = 300 
Initialize the counter for mapping regions 
I= 0 


Create pixmaps for tiling 


PIXMAP 1 = XSCREATE PIXMAP(DPY, WINDOW, PIX WIDTH, PIX_HEIGHT, DEPTH) 


PIXMAP 2 = X$CREATE PIXMAP(DPY, WINDOW, PIX WIDTH, PIX _HEIGHT, DEPTH) 
PIXMAP 3 = XSCREATE PIXMAP(DPY, WINDOW, PIX WIDTH, PIX_HEIGHT, DEPTH) 
CALL X$FILL_RECTANGLE(DPY, PIXMAP_1, GC, 0, 0, PIX WIDTH, 

1 PIX_HEIGHT) 

CALL X$FILL_ RECTANGLE (DPY, PIXMAP 2, GC, 0, 0, PIX_WIDTH, 

1 PIX_HEIGHT) 

CALL X$FILL_ RECTANGLE (DPY, PIXMAP_3, GC, 0, 0, PIX_WIDTH, 

1 PIX HEIGHT) 

CALL XSSET_ FOREGROUND (DPY, GC, DEFINE_COLOR(DPY, SCREEN, 

1 VISUAL, 2)) 

CALL XSDRAW_LINE(DPY, PIXMAP_1, GC, 0, 4, 0, 8) 

CALL X$DRAW LINE(DPY, PIXMAP 2, GC, 4, 0, 8, 0) 

CALL X$DRAW LINE(DPY, PIXMAP 3, GC, 0, 4, 0, 8) 

CALL X$DRAW_LINE(DPY, PIXMAP 3, GC, 4, 0, 8, 0) 


Create the regions 


tl 


REGION 1 
REGION 2 = 


X$POLYGON_REGION(PT_ARR1, 4, X$C_WINDING_ RULE) 
XSPOLYGON REGION (PT _ARR2, 4, X$C_WINDING_ RULE) 


Handle events 


DO WHILE (.TRUE.) 





(continued on next page) 
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Example 6-8 (Cont.) Defining the Intersection of Two Regions 





CALL X$NEXT_EVENT(DPY, EVENT) 


IF (EVENT.EVNT_ TYPE .EQ. X$C_EXPOSE) THEN 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 





i. 150, 25, ‘To map regions click MB1 three times.’) 
CALL X$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, ‘To exit, click MB2’) 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON_PRESS - AND. 
1 EVENT.EVNT_BUTTON.XSL_BTEV_ BUTTON .EQ. X$C_BUTTON1) THEN 
IT=TIetl 
IF (I .EQ. 1) THEN 
C3 CALL X$SET_FILL_STYLE(DPY, GC, X$C_FILL_TILED) 


CALL X$CLEAR_WINDOW(DPY, WINDOW) 
CALL X$SET_TILE(DPY, GC, PIXMAP_1) 


CALL X$SET_REGION(DPY, GC, REGION_1) 


CALL X$FILL_RECTANGLE (DPY, WINDOW, GC, X_ORIGIN, 
1 Y_ORIGIN, WINDOW W, WINDOW_H) 
END IF 
IF (I .EQ. 2) THEN 
6 CALL X$CLEAR_WINDOW(DPY, WINDOW) 
CALL X$SET_TILE(DPY, GC, PIXMAP_ 2) 
CALL X$SET_REGION(DPY, GC, REGION 2) 
CALL X$FILL_RECTANGLE (DPY, WINDOW, GC, X_ORIGIN, 
1 Y_ORIGIN, WINDOW_W, WINDOW_H) 
END IF 
IF (I .EQ. 3) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW) 


7) REGION 3 = X$CREATE_REGION( ) 
CALL XS$INTERSECT REGION (REGION 1, REGION 2, 
1 REGION_3) 
CALL X$SET_TILE(DPY, GC, PIXMAP_3) 
CALL X$SET_REGION(DPY, GC, REGION_3) 
CALL X$FILL_RECTANGLE(DPY, WINDOW, GC, X_ORIGIN, 
1 Y_ORIGIN, WINDOW W, WINDOW_H) 
END IF 
IF (I .GT. 3) THEN 
3 CALL X$SET_ FILL STYLE (DPY, GC, X$C_FILL_SOLID) 
CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC, 
1 150, 75, ‘That’’s it! Click MB2 to exit.’) 
END IF 
END IF 


ots 





@ Arrays of point data structures define two regions. 


@ The pixmaps are used to tile the window with horizontal, vertical, and 
cross-hatched lines. For information about pixmaps, see Chapter 7. 


© After writing messages in the window, the fill style defined in the 
GC data structure is changed to tile the window with pixmaps. The 
subsequent call to SET TILE defines one of the three pixmaps created 
earlier as the window background pixmap. For information about fill 
styles and tiling, see Chapter 4. 
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@ The SET REGION routine specifies the clipping region in the graphics 


context. The region defined by PT_ARR1 is first specified. 


FILL RECTANGLE repaints the window, filling it with the tiling 
pattern defined in PIXMAP_1. Tiling is restricted to the region defined 
by REGION_1. 


Before specifying a new tiling pattern and region, the window is 
cleared. 


@ CREATE REGION creates an empty region and returns an identifier, 


© 


REGION_3. Xlib returns the results of intersecting REGION_1 and 
REGION_2 to REGION_3. 


Before displaying a final message in the window, the fill style is 
redefined to solid to enable text writing. 


Figure 6-14 illustrates the output from the program. 


Figure 6-14 Intersection of Two Regions 


Intersection of Two Regions 
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6.8 Defining Cursors 


A eursor is a bit image on the screen that indicates either the movement 
of a pointing device or the place where text will next appear. Xlib enables 
clients to associate a cursor with each window they create. After making 
the association between cursor and window, the cursor is visible whenever 
it is in the window. If the cursor indicates movement of a pointing device, 
the movement of the cursor in the window automatically reflects the 
movement of the device. 


Xlib and VMS DECwindows provide fonts of predefined cursors. Clients 
that want to create their own cursors can either define a font of shapes 
and masks or create cursors using pixmaps. 


This section describes the following: 


e Creating cursors using the Xlib cursor font, a font of shapes and 
masks, and pixmaps 


e §=6Associating cursors with windows 
¢ Managing cursors 


e Freeing memory allocated to cursors when clients no longer need them 


6.8.1. Creating Cursors 


Xlib enables clients to use predefined cursors or to create 

their own cursors. To create a predefined Xlib cursor, use the 
CREATE FONT CURSOR routine. Xlib cursors are predefined in 
SYS$LIBRARY:DECW$XLIBDEF. Table 6-6 lists the constants that 
refer to the predefined Xlib cursors. 


Table 6-6 Predefined Xlib Cursors 


x$c_X_cursor x$c_arrow_cursor 
x$c_based_arrow_down_cursor x$c_based_arrow_up_cursor 
x$c_boat_cursor x$c_bogosity_cursor 
x$c_bottom_left_corner_cursor x$c_bottom_right_corner_cursor 
x$c_bottom_side_cursor x$c_bottom_tee_cursor 
x$c_box_spiral_cursor x$c_center_ptr_cursor 
x$c_circle_cursor x$c_clock_cursor 
x$c_coffee_mug_cursor x$c_cross_cursor 
x$c_cross_reverse_cursor x$c_crosshair_cursor 
x$c_diamond_cross_cursor x$c_dot_cursor 
x$c_dotbox_cursor x$c_double_arrow_cursor 
x$c_draft_large_cursor x$c_draft_small_cursor 
x$c_draped_box_cursor x$c_exchange_cursor 
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Table 6-6 (Cont.) Predefined Xlib Cursors 


x$c_fleur_cursor 
x$c_gumby_cursor 
x$c_hand2_cursor 
x$c_icon_cursor 
x$c_left_ptr_cursor 
x$c_left_tee_cursor 
x$c_ll_angle_cursor 
x$c_man_cursor 
x$c_mouse_cursor 
x$c_pirate_cursor 
x$c_question_arrow_cursor 
x$c_right_side_cursor 
x$c_rightbutton_cursor 
x$c_sailboat_cursor 
x$c_sb_h_double_arrow_cursor 
x$c_sb_right_arrow_cursor 
x$c_sb_v_double_arrow_cursor 
x$c_sizing_cursor 
x$c_spraycan_cursor 
x$c_target_cursor 
x$c_top_left_arrow_cursor 
x$c_top_right_corne_cursor 
x$c_top_tee_cursor 
x$c_ul_angle_cursor 
x$c_ur_angle_cursor 
x$c_xterm_cursor 


x$c_gobbler_cursor 
x$c_hand1_cursor 
x$c_heart_cursor 
x$c_iron_cross_cursor 
x$c_left_side_cursor 
x$c_leftbutton_cursor 
x$c_lr_angle_cursor 
x$c_middlebutton_cursor 
x$c_pencil_cursor 
x$c_plus_cursor 
x$c_right_ptr_cursor 
x$c_right_tee_cursor 
x$c_rtl_logo_cursor 
x$c_sb_down_arrow_cursor 
x$c_sb_left_arrow_cursor 
x$c_sb_up_arrow_cursor 
x$c_shuttle_cursor 
x$c_spider_cursor 
x$c_star_cursor 
x$c_tcross_cursor 
x$c_top_left_corner_cursor 
x$c_top_side_cursor 
x$c_trek_cursor 
x$c_umbrella_cursor 
x$c_watch_cursor 


The following example creates a sailboat cursor, one of the predefined Xlib 
cursors, and associates the cursor with a window: 


INTEGER*4 FONTCURSOR 


FONTCURSOR = X$CREATE_FONT_CURSOR(DPY, X$C_SAILBOAT_CURSOR) 
CALL X$DEFINE_CURSOR(DPY, WIN, FONTCURSOR) 


The DEFINE CURSOR routine makes the sailboat cursor automatically 
visible when the pointer is in window WIN. 


To create a predefined VMS DECwindows cursor, use the CREATE 
GLYPH CURSOR routine. VMS DECwindows cursors are predefined 
in SYS$LIBRARY:DECW$XLIBDEF. Table 6—7 lists the constants that 
refer to the predefined VMS DECwindows cursors. 
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Table 6-7 Predefined VMS DECwindows Cursors 


decw$c_select_cursor decw$c_leftselect_cursor 
decw$c_help_select_cursor decw$c_wait_cursor 
decw$c_inactive_cursor decw$c_resize_cursor 
decw$c_vpane_cursor decw$c_hpane_cursor 
decw$c_text_insertion_cursor decw$c_text_insertion_bl_cursor 
decw$c_cross_hair_cursor decw$c_draw_cursor 
decw$c_pencil_cursor decw$c_rpencil_cursor 
decw$c_center_cursor decw$c_rightselect_cursor 
decw$c_wselect_cursor decw$c_eselect_cursor 
decw$c_x_cursor decw$c_circle_cursor 
decw$c_mouse_cursor decw$c_lpencil_cursor 
decw$c_leftgrab_cursor decw$c_grabhand_cursor 
decw$c_rightgrab_cursor decw$c_leftpointing_cursor 
decw$c_uppointing_cursor decw$c_rightpointing_cursor 


CREATE GLYPH CURSOR selects a cursor shape and cursor mask from 
the VMS DECwindows cursor font, defines how the cursor appears on 
the screen, and assigns a unique cursor identifier. The following example 
illustrates creating the select cursor and associating the cursor with a 
window: 


INTEGER*4 CURSOR_FONT 
INTEGER*4 GLYPHCURSOR 


RECORD/ X$COLOR/ FORE COLOR, BACK COLOR 


CURSOR_FONT = XSLOAD_FONT(DPY, ‘DECWSCURSOR’ ) 

CALL X$SET_FONT(DPY, GC, ‘DECWSCURSOR’ ) 

GLYPHCURSOR = X$CREATE_GLYPH CURSOR(DPY, CURSOR_FONT, 

1 CURSOR_FONT, DECWS$C_SELECT_ CURSOR, 

af DECWSC_SELECT CURSOR + 1, FORE COLOR, BACK_COLOR) 
CALL X$DEFINE_CURSOR(DPY, WIN, GLYPHCURSOR) 


To create client-defined cursors, either create a font of cursor shapes or 
define cursors using pixmaps. In each case the cursor consists of the 
following components: 


¢ Shape—Defines the cursor as it appears without modification in a 
window 


¢ Mask-—Acts as a clip mask to define how the cursor actually appears 
in a window 


¢ Background color—Specifies RGB values used for the cursor 
background 


¢ Foreground color—Specifies RGB values used for the cursor foreground 


*¢ Hot spot—Defines the position on the cursor that reflects movements 
of the pointing device 
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Figure 6-15 illustrates the relationship between the cursor shape and the 
cursor mask. The cursor shape defines the cursor as it would appear on 
the screen without modification. The cursor mask bits that are set to 1 
select which bits of the cursor shape are actually displayed. If the mask 
bit has a value of 1, the corresponding shape bit is displayed whether it 
has a value of 1 or 0. If the mask bit has a value of 0, the corresponding 
shape bit is not displayed. 


In the resulting cursor shape, bits with a 0 value are displayed in the 
specified background color; bits with a 1 value are displayed in the 
specified foreground color. 
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Figure 6-15 Cursor Shape and Cursor Mask 
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To create a client-defined cursor from a font of glyphs, use the CREATE 
GLYPH CURSOR routine, specifying the cursor and mask fonts that 
contain the glyphs. To create a cursor from pixmaps, use the CREATE 
PIXMAP CURSOR routine. The pixmaps must have a depth of one. If the 
depth is not one, the server generates an error. 


The size of the pixmap cursor must be supported by the display on which 
the cursor is visible. To determine the supported size closest to the size 


the client specifies, use the QUERY BEST CURSOR routine. Example 6-9 
illustrates creating a pencil pointer cursor from two pixmaps. 


Example 6-9 Creating a Pixmap Cursor 


PROGRAM PIXMAP_ CURSOR 
INCLUDE ‘SYSSLIBRARY : DECWSXLIBDEF’ 


INTEGER*4 DPY 

INTEGER*4 SCREEN 

INTEGER*4 WINDOW 

INTEGER*4 GC_MASK 

INTEGER*4 ATTR_MASK 

INTEGER*4 GC 

INTEGER*4 FONT 

INTEGER*4 PIXMAP 

INTEGER*4 PENCIL, PENCIL MASK 

INTEGER*4 PENCIL CURSOR 

INTEGER*4 I, STATUS 

INTEGER*4 DEFINE COLOR 

INTEGER*4 WINDOW _X, WINDOW_Y, DEPTH 

LOGICAL*1 PENCIL BITS (32) 

LOGICAL*1 PENCIL MASK BITS (32) 

RECORD /XS$COLOR/ COLOR _DUMMY ! used for the pixmap 
RECORD /X$COLOR/ CURSOR_FOREGROUND ! used for the pixmap 
RECORD /XSCOLOR/ CURSOR_BACKGROUND ! used for the pixmap 
RECORD /XSVISUAL/ VISUAL ! visual type 

RECORD /X$SET_WIN_ATTRIBUTES/ XSWDA ! window attributes 
RECORD /X$GC_VALUES/ XGCVL ! gc values 

RECORD /X$SIZE_HINTS/ XSZHN ! hints 

RECORD /XSEVENT/ EVENT ! input event 

PARAMETER WINDOW _W = 600, WINDOW_H = 600, 

1 PENCIL WIDTH = 16, PENCIL HEIGHT = 16, 

1 PENCIL XHOT = 1, PENCIL YHOT = 15 

DATA PENCIL BITS /’0000’X, ’0070’X, '0000’X, '0088'X, ‘0000'X, 
1 ‘O08C’X, ’0000’X, '0096’X, '0000’X, '0069’X, '0080’X, 
1 *0030'X, '0040’X, ’0010'X, '0020’X, ’0008’X, ‘0010’X, 
1 ‘0004'X, '0008’X, '0002'xX, '0008'X, '’0001’xX, ‘0094’X, 
J. "Q000'X, '0064’X, '0000’X, ‘OO1E’X, '0000’X, '0006’X, 
1 *0000'X, ’0000’X, '0000’X/ 


(continued on next page) 
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Example 6-9 (Cont.) Creating a Pixmap Cursor 


DATA PENCIL MASK BITS /’00’X, 'F8'X, ‘'OO'X, ‘FC’X, '00'X, 


1 'PE’X, 'O0'X, 'FE’X, '80'X, 'PE’X, 'CO’X, ‘TEX, 
1 "RO’X, '3F°X, 'PO’X, '1F’X, 'F8'X, 'OF'X, 'FC'X, 
1 'O7'X, 'FC’X, '03'X, 'FE’X, '01'X, 'FEX, '00'X, 
1 ‘TEX, ‘OO'X, "LEX, '00'X, '07'X, 700'X/ 


Cc 
c Create the pixmap cursor 
c 
oO PIXMAP = X$CREATE PIXMAP(DPY, XSROOT_WINDOW_OF_SCREEN (SCREEN) , 
1 15. Ty 1) 
Qe CALL XS$LOOKUP_COLOR (DPY, XSDEFAULT_COLORMAP_OF_SCREEN (SCREEN) , 
1 ‘BLACK’, COLOR_DUMMY, CURSOR_FOREGROUND) 
CALL X$LOOKUP_COLOR(DPY, X$DEFAULT_COLORMAP_OF_SCREEN (SCREEN) , 
1 ’WHITE’, COLOR_DUMMY, CURSOR_BACKGROUND) 
© PENCIL = X$CREATE PIX FROM BITMAP _DATA(DPY, PIXMAP, PENCIL BITS, 
1 PENCIL WIDTH, PENCIL HEIGHT, 1, 0, 1) 
PENCIL MASK = X$CREATE_PIX_FROM BITMAP_DATA(DPY, PIXMAP, 
1 PENCIL MASK BITS, PENCIL WIDTH, PENCIL HEIGHT, 1, 0, 1) 
e PENCIL CURSOR = X$CREATE_PIXMAP_CURSOR(DPY, PENCIL, PENCIL MASK, 


1 CURSOR_FOREGROUND, CURSOR _BACKGROUND, PENCIL XHOT, 
1 PENCIL YHOT) 
CALL X$DEFINE_CURSOR(DPY, WINDOW, PENCIL CURSOR) 


@ The client first creates a pixmap into which it will draw bit images for 
the cursor and cursor mask. Note that the depth of the pixmap must 
be one. For information about creating pixmaps, see Chapter 7. 


@ The LOOKUP COLOR routine returns the color value associated with 
the named color to the CURSOR_FOREGROUND and CURSOR_ 
BACKGROUND variables. For information about LOOKUP COLOR, 
see Chapter 5. 


© The CREATE PIXMAP FROM BITMAP DATA routine writes an image 
into a specified pixmap. The client uses the routine to write images for 
the cursor and the cursor mask into two pixmaps. 


@ The CREATE PIXMAP CURSOR routine uses the two pixmaps to 
create the pixmap cursor. 


6.8.2 Managing Cursors 


To dissociate a cursor from a window, call the UNDEFINE CURSOR 
routine. After a call to UNDEFINE CURSOR, the cursor associated with 
the parent window is used. If the window is a root window, UNDEFINE 
CURSOR restores the default cursor. UNDEFINE CURSOR does not 
destroy a cursor. Using its identifier, the client can still refer to the cursor 
and associate it with a window. 
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To change the color of a cursor, use the RECOLOR CURSOR routine. If 
the cursor is displayed on the screen, the change is immediately visible. 
For information about defining foreground and background colors, see 
Chapter 5. For information about loading fonts, see Chapter 8. 


6.8.3 Destroying Cursors 


To destroy a cursor, use the FREE CURSOR routine. FREE CURSOR 
deletes the association between the cursor identifier and the specified 
cursor. It also frees memory allocated for the cursor. 
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Xlib enables clients to create and work with both on-screen graphics, such 
as lines and cursors, and off-screen images, such as pixmaps. Chapter 4 
and Chapter 6 describe how to work with on-screen graphics objects. 


This chapter describes how to work with off-screen graphics resources, 
including the following topics: 


¢ Creating and freeing pixmaps 
* Creating and managing bitmap files 


¢ Working with images 





7.1 Creating and Freeing Pixmaps 


A pixmap is an area of memory into which clients can either define an 
image or temporarily save part of a screen. Pixmaps are useful for defining 
cursors and icons, for creating tiling patterns, and for saving portions of a 
window that has been exposed. Additionally, drawing complicated graphics 
sequences into pixmaps and then copying the pixmaps to a window is often 
faster than drawing the sequences directly to a window. 


Use the CREATE PIXMAP routine to create a pixmap. The routine creates 
a pixmap of a specified width, height, and depth. If the width or height is 
zero or the depth is not supported by the drawable root window, the server 
returns an error. The pixmap must be associated with a window, which 
can be either an input-output or an input-only window. 


Example 7-1 illustrates creating a pixmap to use as backing store for 
drawing the star of Example 6-5. 
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Example 7-1 Creating a Pixmap 





c Create window WINDOW on display DPY, defined 
c as follows: 
Cc Position: x = 100,y = 100 
c Width = 600 
c Height = 600 
c GC refers to the graphics context 
INTEGER*4 PIXMAP 
INTEGER*4 EXPOSE FLAG 
Cc 
Cc Create graphics context 
Cc 
GC_MASK = X$M_GC_FOREGROUND .OR. X$M_GC_BACKGROUND 
Oo XGCVL.X$L_GCVL_FOREGROUND = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 3) 
XGCVL.X$L_GCVL_BACKGROUND = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 3) 
GC = XSCREATE_GC (DPY, WINDOW, GC_MASK, XGCVL) 
Cc 
Cc Create the pixmap 
Cc 
e PIXMAP = XSCREATE_PIXMAP (DPY, WINDOW, WINDOW_W, WINDOW_H, DEPTH) 
3 CALL X$FILL_RECTANGLE(DPY, PIXMAP, GC, 0, 0, WINDOW_W, 
1 WINDOW_H) 
CALL X$SET_FOREGROUND (DPY, GC, DEFINE _COLOR(DPY, SCREEN, 
1 VISUAL, 2)) 
4) CALL X$FILL_POLYGON(DPY, PIXMAP, GC, PT_ARR, 6, X$C_COMPLEX, 
1 X$C_COORD_MODE_ORIGIN) 
Cc 
C Handle events 
Cc 
DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT (DPY, EVENT) 
IF (EVENT.EVNT TYPE .EQ. X$C_EXPOSE) THEN 
CALL XSDRAW IMAGE STRING(DPY, WINDOW, GC, 
1 150, 25, 'To create a filled polygon, click MB1’) 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW, GC, 
1 150, 75, ‘To exit, click MB2’) 
5] IF (EXPOSE FLAG .EQ. 0) THEN 
EXPOSE FLAG = 1 
ELSE 
CALL X$COPY_AREA(DPY, PIXMAP, WINDOW, GC, 0, 0, 
1 WINDOW_W, WINDOW_H, 0, 0) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, 'To exit, click MB2’) 
END IF 
END IF 





(continued on next page) 
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Example 7-1 (Cont.) Creating a Pixmap 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS .AND. 


1 EVENT. EVNT_ BUTTON. X$L_BTEV_BUTTON HO. X$C_BUTTON1) THEN 
CALL XSCOPY_ AREA (DPY, PIXMAP, WINDOW, GC, 0, O, 
1 WINDOW_W, WINDOW_H, 0, 0) 
CALL XS$DRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, ‘To exit, click MB2’) 
ENDIF 
IF (EVENT .EVNT TYPE -BO. X$C_BUTTON_PRESS -AND. 
1 EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON -EQ. X$C_BUTTON2) THEN 
CALL SYSSEXIT(%SVAL(1) ) 
END IF 
END DO 
END 


@ Pixmaps use only the foreground member of the graphics context 
to define color. Because the client is using the pixmap as backing 
store, which is copied into the window to repaint exposed areas, both 
foreground and background members of the graphics context are first 
defined as the window background color. 


@ The pixmap has the width, height, and depth of the window. 


© FILL RECTANGLE fills the pixmap with the background color of the 
window. After filling the pixmap to ensure that pixel values of both 
the pixmap and window background are the same, the foreground color 
is redefined for graphics operations. 


@ After redefining foreground color, the client draws the polygon into 
the pixmap. For a description of specifying and filling the polygon, see 
Example 6-5. 


@ At the first window exposure, the client draws only the text into the 
window. On subsequent exposures, the client copies the pixmap into 
the window to repaint exposed areas. For a description of handling 
exposure events, see Chapter 9. 


When a client no longer needs a pixmap, use the FREE PIXMAP routine to 
free storage associated with it. FREE PIXMAP first deletes the association 
between the pixmap identifier and the pixmap and then frees pixmap 
storage. 





7.2 Creating and Managing Bitmaps 


Xlib enables clients to create files of bitmap data and then use those files 
to create either bitmaps or pixmaps. To create a bitmap data file, use the 
WRITE BITMAP FILE routine. Example 7—2 illustrates creating a pixmap 
and writing the pixmap data into a bitmap data file. 
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Example 7-2 Creating a Bitmap Data File 





PT ARR(1).X$W_GPNT_X = 20 
PT ARR(1).X$W_GPNT_y = 0 
PT ARR(2).X$W_GPNT_X = 20 
PT _ARR(2).X$W_GPNT_Y = 5 


PT ARR(3).X$W_GPNT X = 20 


PT _ARR(3).X$W_GPNT_Y = 10 
PT ARR(4).X$W_GPNT_X = 20 
PT ARR(4).X$W_GPNT_Y = 15 
PT_ARR(5).X$W_GPNT_X = 20 
PT_ARR(5).X$W_GPNT Y = 20 


c Create the pixmap 


PIXMAP = X$CREATE PIXMAP(DPY, WINDOW, PIX WIDTH, PIX_HEIGHT, 
1 DEPTH) 

CALL X$FILL RECTANGLE (DPY, PIXMAP, GC, 0, 0, PIX _WIDTH, 

1 PIX_HEIGHT) 

CALL X$SET FOREGROUND (DPY, GC, DEFINE _COLOR(DPY, SCREEN, 

1 VISUAL, 2)) 

CALL X$DRAW_LINES(DPY, PIXMAP, GC, PT_ARR, 5, X$C_COORD_MODB) 
STATUS = X$WRITE_BITMAP_FILE(DPY, 'BITFILE.DAT’, PIXMAP, 

1 20, 20, 0, QO) 





The client first creates a pixmap using the method described in Section 7.1 
and then calls the WRITE BITMAP FILE routine to write the pixmap data 
into the BITFILE.DAT bitmap file. 


To create a bitmap or pixmap from a bitmap data file, use either the 
CREATE BITMAP FROM DATA or CREATE PIXMAP FROM DATA 
routine. Example 7—3 illustrates creating a pixmap from the bitmap data 
stored in BITFILE.DAT. 


Example 7-3 Creating a Pixmap from Bitmap Data 





INTEGER*4 LINES (60) 


DATA LINES /’AA’X, 'AA’X, ‘OA’X, '55'X, '55'X, '05°X, 
“RA'X, ‘AA'X, 'OA'X, '55'X, '55'X, 'O5'X, ‘AAX, 
"BATX, ‘OA'X, '55’X, '55'X, ’05'X, 'AAX, ‘AAX, 
‘OA’X, '55'X, '55’X, '05’X, "AA’X, ‘AAX, ‘OA'X, 
'55'X, '55'X, '05'X, ‘AA’X, 'AATX, 'OA'X, '55'X, 
'55'X, 'O5'X, “AA’X, ‘AATX, “OA'X, '55°X, '55'X, 
'O5'X, ‘AA'X, 'AA’X, ‘OAK, '55'X, '55°X, '05’'X, 
“RA'X, ‘AA'X, 'OA'X, '55'X, '55°X, '05'X, ‘AAX, 
“RA'X, “OA'X, "55K, '55'°X, '05'X/ 


PRE RPPPRPR 
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aaa 


Create the pixmap 


PIX_FOREGROUND = XGCVL.X$L_GCVL_FOREGROUND 

PIX BACKGROUND = XGCVL.X$L_GCVL_BACKGROUND 

PIXMAP = XSCREATE PIX FROM BITMAP DATA(DPY, WINDOW, LINES, 
1 PIX WIDTH, PIX_HEIGHT, PIX_FOREGROUND, 

1 PIX_BACKGROUND, DEPTH) 

CALL X$SET_WINDOW BACKGROUND PIXMAP (DPY, WINDOW, PIXMAP) 


lou 





The client uses the pixmap to define window background. 





Working with Images 


Instead of managing images directly, clients perform operations on them 
by using the image data structure, which includes a pointer to data such 
as the LINES array defined in Example 7-3. In addition to the image 
data, the image data structure includes pointers to client-defined functions 
that perform the following operations: 


¢ Destroying an image 

¢ Getting a pixel from the image 
¢ Storing a pixel in the image 

e Extracting part of the image 


e Adding a constant to the image 


If the client has not defined a function, the corresponding Xlib routine is 
called by default. 


Figure 7—1 illustrates the data structure. 
Figure 7-1 Image Data Structure 










: 
: 
2 

x$a_imag_data 16 
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Figure 7-1 (Cont.) Image Data Structure 


x$l_imag_byte_order 


x$|_imag_bitmap_unit 


20 













24 






x$l_imag_bitmap_bit_order 28 











: 
x$l_imag_depth 36 
: 
“ 
: 
: 
: 
x$a_imag_obdata 60 
; 
x$a_imag_destroy_image 68 
: 
r 
x$a_imag_sub_image 80 
: 
Table 7-1 describes the members of the data structure. 
Table 7-1 Image Data Structure Members 
Member Name Contents 
X$L_IMAG_WIDTH Specifies the width of the image. 
X$L_IMAG_HEIGHT Specifies the height of the image. 
X$L_IMAG_OFFSET Specifies the number of pixels offset in the x direction. Specifying an offset 


permits the server to ignore the beginning of scanlines and rapidly display 
images when Z pixmap format is used. 
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Table 7-1 (Cont.) Image Data Structure Members 


Member Name 


X$L_IMAG_FORMAT 


X$A_IMAG_DATA 
X$L_IMAG_BYTE_ORDER 
X$L_IMAG_BITMAP_UNIT 
X$L_IMAG_BITMAP_BIT_ORDER 
X$L_IMAG_BITMAP_PAD 


X$L_IMAG_DEPTH 
X$L_IMAG_BYTES_PER_LINE 
X$L_IMAG_BITS_PER_PIXEL 
X$L_IMAG_RED_MASK 
X$L_IMAG_GREEN_MASK 
X$L_IMAG_BLUE_MASK 
X$A_IMAG_OBDATA 
X$A_IMAG_CREATE_IMAGE 
X$A_IMAG_DESTROY_ IMAGE 
X$A_IMAG_GET_PIXEL 
X$A_IMAG_PUT_PIXEL 
X$A_IMAG_SUB_IMAGE 
X$A_IMAG_ADD_PIXEL 


Contents 
Specifies whether the data is stored in XY pixmap or Z pixmap format. The 
following flags facilitate specifying data format: 


Flag Name Description 


x$c_xy_bitmap 
x$c_xy_pixmap 
x$c_z_pixmap 


A single bitmap representing one plane 
A set of bitmaps representing individual planes 


Data organized as a list of pixel values viewed 
as a horizontal row 


Address of the image data. 

Indicates whether least significant or most significant byte is first. 
Specifies whether the bitmap is organized in units of 8, 16, or 32 bits. 
Specifies whether the bitmap order is least or most significant. 


Specifies whether padding in XY format or Z format should be done in 
units of 8, 16, or 32 bits. 


Depth of the image. 

Bytes per line to be used as an accelerator. 

Indicates for Z format the number of bits per pixel. 

Specifies the red value of Z format. 

Specifies the green value of Z format. 

Specifies blue values of Z format. 

A data structure that contains object routines. 

Client-defined function that creates an image. 

Client-defined function that destroys an image. 

Client-defined function that gets the value of a pixel in the image. 
Client-defined function that changes the value of a pixel in the image. 
Client-defined function that creates a new image from an existing one. 


Client-defined function that increments each pixel value in the image by a 
constant. 


To create an image, use either the CREATE IMAGE or the GET IMAGE 
routine. CREATE IMAGE initializes an image data structure, including 
a reference to the image data. For example, the following call creates an 
image data structure that points to the image data LINES, illustrated in 
Example 7—3: 
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RECORD /X$IMAGE/ IMAGE 


PARAMETER WINDOW_W = 600, WINDOW_H = 600, 
1 PIX_WIDTH = 16, PIX_HEIGHT = 16, 
1 BITMAP_PAD 16, BYTES PER_LINE 16 


CALL XSCREATE_ IMAGE (DPY, VISUAL, DEPTH, X$C_2 PIXMAP, 
1 0, LINES, PIX_WIDTH, PIX_HEIGHT, BITMAP PAD, 
1 BYTES PER_LINE) 


Note that the CREATE IMAGE routine does not allocate storage space for 
the image data. 


To create an image from a drawable, use the GET IMAGE routine. In the 
following example, the client creates an image from a pixmap: 


PARAMETER X_ORIGIN = 0, Y_ORIGIN = 0, 
1 PIX_WIDTH = 16, PIX_HEIGHT = 16 


IMAGE = X$SGET_IMAGE (DPY, PIXMAP, X_ORIGIN, Y_ORIGIN, 
1 PIX_WIDTH, PIX_HEIGHT, XGCVL.X$L_GCVL_PLANE_MASK, 
1 X$C_Z_PIXMAP) 


To transfer an image from memory to a drawable, use the PUT IMAGE 
routine. In the following example, the client transfers the image from 
memory to a window: 


PARAMETER SRC_X = 0, SRC_Y = 0, 
i DST_X = 200, DST_Y = 200, 
1 PIX WIDTH = 16, PIX_HEIGHT = 16 


| oi 


CALL X$PUT_IMAGE(DPY, WINDOW, GC, IMAGE, SRC_X, SRC_Y, 
1 DST_X, DST Y, PIX WIDTH, PIX HEIGHT) 


The call transfers the entire image, which was created in the call to GET 
IMAGE, from memory to coordinates (200, 200) in the window. 


As the description of the image data structure indicates, Xlib enables 
clients to store an image in the following ways: 


As a bitmap—XY bitmap format stores the image as a two-dimensional 
array. Figure 7—2 illustrates XY bitmap format. 


As a set of bitmaps—xXY pixmap format stores the image as a stack of 
bitmaps. Figure 7-3 illustrates XY pixmap format. 


Using Pixmaps and Images 
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e Asa list of pixel values—Z pixmap format stores the image as a list of 
pixel values viewed as a horizontal row. Each example of creating an 
image uses Z pixmap format. Figure 7—4 illustrates scanline order. 


Figure 7-2 XY Bitmap Format 


XY Bitmap Format 
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Figure 7~3 XY Pixmap Format 


XY Pixmap Format 
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Figure 7-4 Z Format 





Z Pixmap Format 
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Xlib includes routines to change images by manipulating their pixel values 
and creating new images out of subsections of existing images. Table 7-2 
lists these routines and their use. Clients can override these routines by 
defining functions referred to in the image data structure. 


Table 7-2 Routines That Change Images 


Routine 


ADD PIXEL 
GET PIXEL 
PUT PIXEL 
SUB IMAGE 


Description 


Increments each pixel in an image by a constant value 
Returns the pixel value of an image 

Sets the pixel value of an image 

Creates a new image out of a subsection of an existing image 


When a client no longer needs an image, use the DESTROY IMAGE 
routine to deallocate memory associated with the image data structure. 
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Writing Text 


This chapter describes writing text using Xlib. The chapter includes the 
following topics: 


¢ Characters and fonts—A description of the composition of characters 
and types of fonts and their components 


¢ Specifying fonts—How to load a font and associate it with a graphics 
context 


* Computing text size—How to determine the size of text 

¢ Getting information about text—How to get information about text 
¢ Drawing text—How to write text on the screen 

VMS DECwindows provides a font compiler to enable programmers 


to convert ASCII files into binary form. For a guide to using the font 
compiler, see Appendix A. 





Characters and Fonts 


The smallest unit of text the server displays on a screen is a character. 
Pixels that form a character are enclosed within a bounding box that 
defines the number of pixels the server turns on or off to represent the 
character on the screen. For example, Figure 8—1 illustrates the bounding 


«, 


box that encloses the character “y.” 


The server turns each pixel within the bounding box either on or off, 
depending on the character. Consequently, bounding box size affects 
performance. Larger bounding boxes require more server time to process 
than do smaller boxes. 


The character is positioned relative to the baseline and the character 
origin. The baseline is logically viewed as the x axis that runs just below 
nondescending characters. The character origin is a point along the 
baseline. The left bearing of the character is the distance from the origin 
to the left edge of the bounding box; the right bearing is the distance 
from the origin to the right edge. Ascent and descent measure the 
distance from the baseline to the top and bottom of the bounding box, 
respectively. Character width is the distance from the origin to the next 
character origin ( x + width, y). 
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Figure 8-1 Composition of a Character 
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Figure 8-2 illustrates that the bounding box of a character can extend 
beyond the character origin. The bounding box of the back slash extends 
one pixel to the left of the origin of the slash, giving the character a 
left bearing of —1. The back slash is aiso unusual because its bounding 
box extends to the right of the next character. The width of the slash, 
measured from origin to origin, is 5; the right bearing, measured from 
origin to the right edge of the bounding box, is 6. 
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Figure 8-2 Composition of a Back Slash 
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The left bearing , right bearing, ascent, descent, and width of a character 
are its character metrics. Xlib maintains information about character 
metrics in a char struct data structure. Figure 8-3 illustrates the data 
structure. 


Figure 8-3 Char Struct Data Structure 











x$w_char_rbearing x$w_char_lbearing 
x$w_char_attributes x$w_char_descent 


Table 8-1 describes members of the char struct data structure. Any 
member of the data structure can have a negative value, except the 
X$W_CHAR_ATTRIBUTES member. 
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Table 8-1 Char Struct Data Structure Members 


Member Name Contents 

X$W_CHAR_LBEARING Distance from the origin to the left edge of the 
bounding box. 

X$W_CHAR_RBEARING Distance from the origin to the right edge of the 
bounding box. 

X$W_CHAR_WIDTH Distance from the current origin to the origin of 


the next character. Text written left to right, such 
as Arabic, uses a negative width to place the next 
character to the left of the current origin. 


X$W_CHAR_ASCENT Distance from the baseline to the top of the 
bounding box. 

X$W_CHAR_DESCENT Distance from the baseline to the bottom of the 
bounding box. 

X$W_CHAR_ATTRIBUTES Attributes defined in the bitmap distribution format 
file. A character is not guaranteed to have any 
attributes. 


A font is a group of characters that have the same style and size. Xlib 
supports both fixed and proportional fonts. A fixed font has equal 
metrics. For example, all characters in the font have the same value 
for left bearing. Consequently, the bounding box for all characters is the 
same. All metrics in a proportional font can vary from character to 
character. A monospaced font is a special type of proportional font in 
which only the width of all characters must be equal. Bounding boxes of 
characters in a monospaced font vary depending on the size of characters. 
If the same font is compiled as a monospaced font and a fixed font, the 
bounding boxes of the monospaced font are typically smaller than the 
bounding box that encloses fixed-font characters. For information about 
compiling fonts, see Appendix A. 


Xlib uses indexes to refer to characters that compose a font. The indexes, 
each defined by a byte, are arranged in one or more rows of up to 256 
indexes. A font can contain as many as 256 rows of character indexes, 
used contiguously. Fonts seldom use all possible indexes. 


For example, the font illustrated in Figure 8-4 comprises 219 characters 
in columns 32 through 250, one column for each character index. Columns 
1 through 31 and 251 through 256 are undefined. The first character of 
the font is located at column 32; the last character is located at column 
250. Because all characters are defined in one row of 256 indexes, the 
font is a single-row font. In the illustration, character “A” is located at 
column 65. 
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Figure 8-4 Single-Row Font 
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Multiple-row fonts, such as Kanji, comprise more characters than 

can be indexed by a single row of 256 bytes. Figure 8-5 illustrates the 
configuration of a multiple-row font. Byte 1 refers to the row. Byte 2 
refers to the column in the row. In Figure 8—5, the character is located at 
column 36 in row 17. Note that each row of a multiple-row font has the 
same number of undefined bytes at the beginning and end. In each row, 
characters begin at column 32 and end at column 250. 


Figure 8-5 Multiple-Row Font 
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Xlib provides a char 2B data structure to enable clients to index multiple- 
row fonts easily. Figure 8—6 illustrates the data structure. 


Figure 8-6 Char 2B Data Structure 


x$t_ch2b_byte2 x$t_ch2b_byte1 


Table 8—2 describes members of the data structure. 


Table 8-2 Char 2B Data Structure Members 


Member Name Contents 
X$T_CHAR2B_BYTE1 Row in which the character is indexed 
X$T_CHAR2B_BYTE2 Position of the character in the row 


Xlib provides clients a font struct data structure to record the 
characteristics of single-row and multiple-row fonts. Figure 8—7 illustrates 
the font struct data structure. 


Figure 8-7 Font Struct Data Structure 
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Figure 8-7 (Cont.) Font Struct Data Structure 


x$a_fstr_per_char 


x$l_fstr_ascent 


x$l_fstr_descent 





Table 8-3 describes members of the data structure. 


Table 8-3 Font Struct Data Structure Members 


Member Name 


X$A_FSTR_EXT_DATA 
X$L_FSTR_FID 
X$L_FSTR_DIRECTION 


X$L_FSTR_MIN_CHAR_OR_BYTE2 
X$L_FSTR_MAX_CHAR_OR_BYTE2 
X$L_FSTR_MIN_BYTE1 
X$L_FSTR_MAX_BYTE1 
X$L_FSTR_ALL_CHARS_EXIST 


X$L_FSTR_DEFAULT_CHAR 


X$L_FSTR_N_PROPERTIES 
X$A_FSTR_PROPERTIES 


X$R_FSTR_MIN_BOUNDS 


Contents 


Data used by extensions. 

Identifier of the font. 

Hint about the direction in which the font is painted. The direction 
can be either left to right, specified by the constant x$c_font_left_ 
to_right, or right to left, specified by the constant x$c_font_right_to_ 
left. The core protocol does not support vertical text. 

First character in the font. 

Last character in the font. 

First row that exists. 

Last row that exists. 

If the value of this member is true, all characters in the array 


pointed to by X$A_FSTR_PER_CHAR have nonzero bounding 
boxes. 


Character used when an undefined or nonexistent character is 
printed. The default character is a 16-bit, not a 2-byte, character. 
For a multiple-row font, X$L_FSTR_DEFAULT_CHAR has byte 1 in 
the most significant byte and byte 2 in the least significant byte. If 
X$L_FSTR_DEFAULT_CHAR specifies an undefined or nonexistent 
character, the server does not print an undefined or nonexistent 
character. 


Number of properties associated with the font. 

Address of an array of font prop data structures that define font 
properties. For a description of the font prop data structure, see 
Section 8.3 

Minimum metrics values of all the characters in the font. The 
metrics define the left and right bearings, ascent and descent, and 
width of characters. 


For a description of the use of X$R_FSTR_MIN_BOUNDS, see 
X$R_FSTR_MAX_BOUNDS. 
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Table 8-3 (Cont.) Font Struct Data Structure Members 


Member Name 


X$R_FSTR_MAX_BOUNDS 


X$A_FSTR_PER_CHAR 


X$L_FSTR_ASCENT 


X$L_FSTR_DESCENT 


Contents 


Maximum metrics values of all the characters in the font. 


Using the values of X$R_FSTR_MIN_BOUNDS and X$R_FSTR_ 
MAX_BOUNDS, clients can compute the bounding box of a font. 
The bounding box of the font is determined by first computing the 
minimum and maximum value of the left bearing, right bearing, 
width, ascent, and descent of all characters and then subtracting 
minimum from maximum values. The upper left coordinate of the 
font bounding box (x, y) is defined as follows: 


x + X$R_FSTR_MIN_BOUNDS.X$W_CHAR_LBEARING, 
y - X$R_FSTR MAX BOUNDS.X$W_CHAR_ASCENT 


The width of the font bounding box is defined as follows: 


X$R_FSTR_MAX BOUNDS.X$W_CHAR_RBEARING - 
X$R_FSTR_MIN_BOUNDS.X$W_CHAR LBEARING 


Note that this is not the width of a font character. 
The height is defined as follows: 


X$R_FSTR_MAX BOUNDS.X$W_CHAR_ASCENT + 
X$R_FSTR_MAX BOUNDS.X$W_CHAR DESCENT 


Address of an array of char struct data structures that define each 
character in the font. For a fixed font, the value of this member is 
null. 


Distance from the baseline to the top of the bounding box. With 
X$L_FSTR_DESCENT, X$L_FSTR_ASCENT is used to determine 
line spacing. Specific characters in the font may extend beyond the 
font ascent. 


The distance from the baseline to the bottom of the bounding 
box. With X$L_FSTR_ASCENT, X$L_FSTR_DESCENT is used to 
determine line spacing. Specific characters in the font may extend 
beyond the font descent. 





As Table 8-3 indicates, Xlib records metrics for each character in an array 
of char struct data structures specified by the font struct X$A_FSTR_PER_ 


CHAR member. The array comprises as many char struct data structures 
as there are characters in the font. However, the indexes that refer to the 


hat 


location of characters in the array differs from the indexes to characters in 
the font. For example, 32 indexes the first character of the font illustrated 
in Figure 8-8, whereas 0 indexes its char struct data structure in the 
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Figure 8-8 Indexing Single-Row Font Character Metrics 
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To locate the char struct data structure that defines the metrics of any 
character in a single-row font, subtract the value of the column that 
indexes the first character in the font, specified by X$L_FSTR_MIN_ 
CHAR_OR_BYTE_2, from the position of the character. Then add 1 to 
this number. For instance, in Figure 8-8 the metrics of character “A” are 
located at index 34 in the array of char struct data structures specified by 
the X$A_FSTR_PER_CHAR member. 


To locate the char struct data structure that defines the metrics of a 
character of a mulitple-row font, use the following formula to adjust for 
both the number of rows in the font and the position of the character in a 
row: 


(row — first row of characters) * N + (position in column — first column) 
N is equal to the last column minus the first column plus 1. 


For example, the array index of the character specified in Figure 8-9 
is 443. 
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Figure 8-9 Indexing Multiple-Row Font Character Metrics 
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Like windows, fonts may have properties associated with them. However, 
font properties differ from window properties. Window properties are data 
associated with windows; font properties describe font characteristics, such 
as spacing between words. When the font is compiled, its properties are 
defined in an array of font prop data structures. 
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Just as atoms name window properties, atoms name font properties. If 
the atoms are predefined, they have associated literals. For example, the 
predefined atom that identifies the height of capitalized letters is referred 
to by the literal X$C_XA_CAP_HEIGHT. 


When working with properties, clients must know beforehand how to 
interpret the font property identified by an atom. Figure 8-10 illustrates 
this concept. 


The server maintains an atom table for font properties. The table 
associates values with strings. For example, the atom table illustrated 

in Figure 8-10 defines two atoms. One associates the string FULL_NAME 
with the value 41. The other associates the string CAP_HEIGHT with 
the value 42. Notice that the string in the atom table is different from 
X$C_XA_FULL_NAME, the literal that refers to the atom. 


Both atoms uniquely identify different types of data. FULL_NAME 
identifies string data that names the font. CAP_HEIGHT identifies integer 
data that defines the size of capitalized letters. 


Although the atoms identify different types of data, the property table 
illustrated in Figure 8-10 associates both atoms with integers. The integer 
associated with CAP_HEIGHT defines without further interpretation the 
height of capitalized letters. However, the integer listed with FULL_ 
NAME is an atom value. This integer, 90, corresponds to a value in the 
atom table that has an associated string, HELVETICA BOLD. To use the 
string, the client must know that the value associated with the atom is 
itself an atom value. 
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Figure 8-10 Atoms and Font Properties 
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Xlib lists each font property and its corresponding atom in a font prop data 
structure. The property value table in Figure 8-10 is an array of font prop 


data structures. 


Figure 8-11 illustrates the font prop data structure. 
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Figure 8-11 Font Prop Data Structure 


x$l_fntp_name 0 
x$l_fntp_card32 4 





Table 8—4 describes members of the data structure. 


Table 8-4 Font Prop Data Structure Members 





Member Name Contents 

X$L_FNTP_NAME String of characters that names the property 

X$L_FNTP_CARD32 A 32-bit value that defines the font property 
Specifying a Font 


To specify a font for writing text, first load the font and then associate the 
loaded font with a graphics context. Appendix D lists VMS DECwindows 
fonts. 


To load a font, use either the LOAD FONT or the LOAD QUERY FONT 
routine. LOAD FONT loads the specified font and returns a font identifier. 
LOAD QUERY FONT loads the specified font and returns information 
about the font to a font struct data structure. 


Because LOAD QUERY FONT returns information to a font struct data 
structure, calling the routine takes significantly longer than calling LOAD 
FONT, which returns only the font identifier. 


When using either routine, pass the display identifier and font name. Xlib 
font names consist of the following fields, in left to right order: 


1 Foundry that supplied the font, or the font designer 
Typeface family of the font 

Weight (book, demi, medium, bold, light) 

Style (R (roman), I (italic), O (oblique)) 


Width per horizontal unit of the font (normal, wide, double wide, 
narrow) 


Additional style font identifier 


oa fF @®W N 


Pixel font size 
Point size (8, 10, 12, 14, 18, 24) 


eo ON oO 


Resolution in pixels/dots per inch 

10 Spacing (monospaced, proportional, or character cell) 

11 Average width of all characters in the font 

12 Set character encoding 8-13 


Writing Text 
8.2 Specifying a Font 


The full name of a representative font in 
SYS$SYSROOT:[DECW$FONT.100DPI] is as follows: 


-ADOBE-ITC Avant Garde Gothic—-Book~R-Normal--14-100-100-100-P-—80-IS08859-1 


The font is named ITC Avant Garde Gothic. Font weight is book, font style 
is R (roman), and width between font units is normal. 


The pixel size is 14 and the decipoint size is 100. 


Horizontal and vertical resolution in dots per inch (dpi) is 100. When the 
dpi is 100, 14 pixels are required to be a 10 point font. 


The font is proportionally spaced. Average width of characters is 80. 
Character encoding is ISOLATIN1. 


The following designates the full name of the comparable font designed for 
a 75 dpi system: 


-ADOBE-ITC Avant Garde Gothic-Book-R-Normal--10-100-75-75—-P-59-IS08859-1 


Unlike the previous font, this font requires only 10 pixels to be 10 points. 
Note that this font differs from the previous font only in pixel size, 
resolution, and character width. 


Xlib enables clients to substitute a question mark for a single character 
and an asterisk for one or more fields in a font name. The following 
illustrates using the asterisk to specify a 10-point ITC Avant Garde Gothic 
font of book weight, roman style, and normal spacing for display on either 
75 or 100 dpi systems: 


-ADOBE-ITC Avant Garde Gothic-Book-R-Normal--*-100-*-*-P-* 


When using the asterisk, make sure that substitutions are clearly defined. 
For example, the following name ambiguously specifies two fonts: 


-ADOBE-ITC Avant Garde Gothic-Book—-R-Normal--*-100-*-P-* 


Because the leftmost asterisk substitutes for all fields before the 100, the 
name defines the following two 100 dpi fonts: 


-ADOBE-ITC Avant Garde Gothic-—Book-R-Normal--11-80-100-100-P-80-IS08859-1 


-ADOBE-ITC Avant Garde Gothic-Book-R-Normal--14-100-100-100-P-80-IS08859-1 
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The first is an 8 point font. The second is a 10 point font. 


The following example illustrates loading the 10-point font: 


CHARACTER*58 FONT NAME 
DATA FONT_NAME 
1 /’-ADOBE-ITC AVANT GARDE GOTHIC-BOOK-R~NORMAL-—*-100-*-*—P-*! / 


FONT = X$LOAD FONT(DPY, FONT NAME) 


Writing Text 
8.2 Specifying a Font 


After loading a font, associate it with a graphics context by calling the 
SET FONT routine. Specify the font identifier that either LOAD FONT or 
LOAD QUERY FONT returned, and a graphics context, as in the following 
example: 


CALL XSSET_FONT(DPY, GC, FONT) 
The call associates FONT with GC. 





8.3 Getting Informati 


on About a Font 


Xlib provides clients with routines that list available fonts, get font 
information with or without character metrics, and return the value of 
a specified font property. 


To get a list of available fonts, use the LIST FONTS routine, specifying the 
font searched for. 


LIST FONTS returns a list of available fonts that match the specified font 
name. When the client no longer needs the list of font names, call the 
FREE FONT NAMES routine to free storage allocated for the font list. 


To receive both a list of fonts and information about the fonts, use the 
LIST FONTS WITH INFO routine. LIST FONTS WITH INFO returns 
both a list of fonts that match the font specified by the client and the 
address of a font struct data structure for each font listed. Each data 
structure contains information about the font. The data structure does not 
include character metrics in the X$A_FSTR_PER_CHAR member. For a 
description of the information returned, see Table 8—3. 


To receive information about a font, including character metrics, use the 
QUERY FONT routine. Because the server returns character metrics, 
calling QUERY FONT takes approximately eight times longer than calling 
LIST FONTS WITH INFO. To get the value of a specified property, use the 
GET FONT PROPERTY routine. 


Although a font is not guaranteed to have any properties, it should have 
at least the properties described in Table 8-5. The table lists properties 
by atom name and data type. For information about properties, see 
Section 3.5. 


Table 8-5 Atom Names of Font Properties 


Atom 


X$C_XA_MIN_SPACE 
X$C_XA_NORMAL_SPACE 
X$C_XA_MAX_SPACE 
X$C_XA_END_SPACE 


Data Type Description of the Property 

Unsigned Minimum interword spacing, in pixels. 

Unsigned Normal interword spacing, in pixels. 

Unsigned Maximum interword spacing, in pixels. 

Unsigned Additional spacing at the end of a sentence, in pixels. 


(continued on next page) 
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8.3 Getting Information About a Font 


Table 8-5 (Cont.) Atom Names of Font Properties 


Atom Data Type 
X$C_XA_SUPERSCRIPT_X Signed 
X$C_XA_SUPERSCRIPT_Y Signed 
X$C_XA_SUBSCRIPT_X Signed 
X$C_XA_SUBSCRIPT_Y Signed 


X$C_XA_UNDERLINE_POSITION Signed 


X$C_XA_UNDERLINE_THICKNESS — Unsigned 
X$C_XA_STRIKEOUT_ASCENT Signed 


X$C_XA_STRIKEOUT_DESCENT Signed 


X$C_XA_ITALIC_ANGLE Signed 
X$C_XA_X_HEIGHT Signed 
X$C_XA_QUAD_WIDTH Signed 


Description of the Property 


With X$C_XA_ SUPERSCRIPT_Y, the offset from the 
character origin where superscripts should begin, in 
pixels. If the origin is [x, y], superscripts should begin at 
the following coordinates: 


x + X$C_XA_SUPERSCRIPT_X, 
y - X$C_XA_SUPERSCRIPT_Y 


With X$C_XA_SUPERSCRIPT_X, the offset from 
the character origin where superscripts should begin, 
in pixels. See the description under X$C_XA_ 
SUPERSCRIPT_X. 


With X$C_XA_SUBSCRIPT_Y, the offset from the 
character origin where subscripts should begin, in pixels. 
if the origin is [x, y], subscripts should begin at the 
following coordinates: 


x + X$C_XA_SUBSCRIPT_X, 
y + X$C_XA_SUBSCRIPT_Y 


With X$C_XA_SUBSCRIPT_X, the offset from the 
character origin where subscripts should begin, in pixels. 
See the description under X$C_XA_SUBSCRIPT_X. 


The y offset from the baseline to the top of an underline, 
in pixels. If the baseline y-coordinate is y, then the 

top of the underline is at y + X$C_XA_UNDERLINE_ 
POSITION. 


Thickness of the underline, in pixels. 


With X$C_XA_STRIKEOUT_DESCENT, the vertical 
extent for boxing or voiding characters, in pixels. If the 
baseline y-coordinate is y, the top of the strikeout box is 
y - X$C_XA_STRIKEOUT_ASCENT. The height of the 
box is as follows: 


X$C_XA_STRIKEOUT_ASCENT + 
X$C_XA_STRIKEOUT_ DESCENT 


With X$C_XA_STRIKEOUT_ASCENT, the vertical extent 
for boxing or voiding characters, in pixels. See the 
description under X$C_XA_STRIKEOUT_ASCENT. 


The angle of the dominant staffs of characters in the font, 
in degrees scaled by 64, relative to the 3-o’clock position 
from the character origin. Positive values indicate 
counterclockwise motion. 


One ex, as in TeX, but expressed in units of pixels. 
Often the height of lowercase x. 


One em, as in TeX, but expressed in units of pixels. 
Often the width of the digits 0 to 9. 
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Table 8-5 (Cont.) Atom Names of Font Properties 





Atom 


X$C_XA_CAP_HEIGHT 


X$C_XA_WEIGHT 
X$C_XA_POINT_SIZE 
X$C_XA_RESOLUTION 


X$C_XA_COPYRIGHT 
X$C_XA_NOTICE 
X$C_XA_FONT_NAME 
X$C_XA_FAMILY_NAME 
X$C_XA_FULL_NAME 


Data Type Description of the Property 


Signed The y offset from the baseline to the top of capital letters, 
ignoring ascents. If the baseline y-coordinate is y, the 
top of the capitals is at y - X$C_XA_CAP_HEIGHT. 


Unsigned Weight or boldness of the font, expressed as a value 
between 0 and 1000. 

Unsigned Point size of the font at ideal resolution, expressed in 
1/10 points. 

Unsigned Number of pixels per point, expressed in 1/100, at which 
the font was created. 

Unsigned Copyright date of the font. 

Unsigned Copyright date of the font name. 

Atom Font name. 

Atom Name of the font family. 

Atom Full name of the font. 


Computing the Size of Text 


Use the TEXT WIDTH and TEXT WIDTH 16 routines to compute the 
width of 8-bit and 2-byte strings, respectively. The routines return the 
sum of the width of each character in the specified string. To compute the 
bounding box of a specified 8-bit string, use either the TEXT EXTENTS 
or QUERY TEXT EXTENTS routine. Both TEXT EXTENTS and QUERY 
TEXT EXTENTS return the direction hint, ascent, descent, and overall 
size of the character string being queried. 


TEXT EXTENTS passes to Xlib the font struct data structure returned 
by a previous call to either LOAD QUERY FONT or QUERY FONT. 
QUERY TEXT EXTENTS queries the server for font information, which 
the server returns to a font struct data structure. Because Xlib can process 
TEXT EXTENTS locally, without querying the server for font metrics, 
calling TEXT EXTENTS is significantly faster than calling QUERY TEXT 
EXTENTS. 


To compute the bounding boxes of a specified 2-byte string, use either the 
TEXT EXTENTS 16 or the QUERY TEXT EXTENTS 16 routine. Both 
routines return information identical to information returned by TEXT 
EXTENTS and QUERY TEXT EXTENTS. As with TEXT EXTENTS, 
calling TEXT EXTENTS 16 is significantly faster than calling QUERY 
TEXT EXTENTS 16 because Xlib can process the call without making the 
round-trip to the server. 


8-17 


8.5 


Writing Text 


8.5 Drawing Text 





Drawing Text 
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Xlib enables clients to draw text stored in text data structures, text 
whose foreground bits are only displayed, and text whose foreground and 
background bits are displayed. 


To draw 8-bit or 2-byte text stored in data structures, use either the 
DRAW TEXT or the DRAW TEXT 16 routine. Xlib includes text item and 
text item 16 data structures to enable clients to store text. Figure 8-12 
illustrates the text item data structure. 


Figure 8-12 Text Item Data Structure 






Table 8-6 describes members of the text item data structure. 


Table 8-6 Text Item Data Structure Members 


Member Name 


X$A_TEXT_CHARS 
X$L_TEXT_N_CHARS 
X$L_TEXT_DELTA 


X$L_TEXT_FONT 


Conients 


Address of a string of characters. 
Number of characters in the string. 


Horizontal spacing before the start of the string. 
Spacing is always added to the string origin and is not 
dependent on the font used. 


Identifier of the font used to print the string. If the 
value of this member is x$c_none, the server uses the 
current font in the GC data structure. If the member 
has a value other than x$c_none, the specified font is 
stored in the GC data structure. 


Figure 8-13 illustrates the text item 16 data structure. 


Writing Text 
8.5 Drawing Text 


Figure 8-13 Text Item 16 Data Structure 











Table 8—7 describes members of the text item 16 data structure. 


Table 8-7 Text ltem 16 Data Structure Members 


Member Name Contents 


X$A_TX16_CHARS Address of a string of characters stored in a char 2B 
data structure. For a description of the char 2B data 
structure, see Figure 8-6. 


X$L_TX16_N_CHARS Number of characters in the string. 

X$L_TX16_DELTA Horizontal spacing before the start of the string. Spacing 
is always added to the string origin and is not dependent 
on the font used. 

X$L_TX16_FONT Identifier of the font used to print the string. !f the value 
of this member is x$c_none, the server uses the current 
font in the GC data structure. If the member has a value 


other than x$c_none, the specified font is stored in the 
GC data structure. 


Xlib processes each text item in turn. Each character image, as defined by 
the font in the graphics context, is treated as an additional mask for a fill 
operation on the drawable. The drawable is modified only where the font 
character has a bit set to 1. 


Example 8—1 illustrates using the DRAW TEXT routine to draw three 
words in one call. 
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8.5 Drawing Text 


Example 8-1 Drawing Text Using the DRAW TEXT Routine 





RECORD /X$TEXT_ITEM/ TEXT_ARR (3) 


CHARACTER*57 FIRST FONT 
DATA FIRST FONT 
1 /’-ADOBE-NEW CENTURY SCHOOLBOOK-BOLD~R-NORMAL--*-80-*-*=P=*! / 


CHARACTER*58 SECOND _FONT 
DATA SECOND FONT 
1 /'’-ADOBE-NEW CENTURY SCHOOLBOOK~BOLD-R-NORMAL-~-—*~-140-*-*-P—*! / 


CHARACTER*58 THIRD _FONT 
DATA THIRD FONT 
1 /'-ADOBE-NEW CENTURY SCHOOLBOOK-BOLD-R-NORMAL--*-240-*-*-P—*! / 


CHARACTER*5 FIRST_WORD 
DATA FIRST_WORD /’ SMALL’ / 


CHARACTER*6 SECOND_WORD 
DATA SECOND_WORD /’ BIGGER’ / 


CHARACTER*7 THIRD WORD 
DATA THIRD _WORD /’ BIGGEST’ / 


Load the fonts for text writing 


FONT _1 = X$LOAD_FONT(DPY, FIRST_FONT) 


TEXT _ARR(1).X$A_TEXT_CHARS = %LOC (FIRST WORD) 
TEXT ARR(1).X$L_TEXT_N CHARS = 5 

TEXT ARR(1).X$L_TEXT DELTA = 0 

TEXT ARR(1).X$L_TEXT FONT = FONT 1 


FONT_2 = X$LOAD_FONT(DPY, SECOND FONT) 
CALL X$SET_FONT(DPY, GC, FONT 2) 


TEXT_ARR(2) .X$A_TEXT_CHARS = %LOC(SECOND_WORD) 
TEXT ARR(2).X$L_TEXT_N CHARS = 6 
TEXT_ARR(2).X$L_TEXT DELTA = 20 
TEXT_ARR(2).X$L_TEXT_ FONT = FONT 2 


FONT_3 = X$LOAD_ FONT(DPY, THIRD_FONT) 


TEXT_ARR(3) .X$A_TEXT_CHARS = %LOC (THIRD WORD) 
TEXT_ARR(3).X$L_TEXT_N CHARS = 7 
TEXT_ARR(3).X$L_TEXT DELTA = 20 
TEXT_ARR(3).X$L_TEXT_FONT = FONT_3 
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Example 8-1 (Cont.) Drawing Text Using the DRAW TEXT Routine 


Cc 
Cc Handle events 
Cc 
DO WHILE (.TRUE.) 
CALL X$NEXT_EVENT(DPY, EVENT) 
IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 


CALL XS$DRAW_IMAGE STRING(DPY, WINDOW, GC, 


AND. 


X$C_BUTTON1) THEN 
200, TEXT ARR(1), 3) 


1 150, 25, ‘To draw text, click MB1’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 50, ‘To exit, click MB2’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS 
1 EVENT .EVNT_BUTTON.X$L_BTEV_BUTTON -EQ. 
CALL XSDRAW_TEXT(DPY, WINDOW, GC, 100, 
END IF 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS 
1 EVENT.EVNT_ BUTTON.X$L_BTEV_ BUTTON .EQ. 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
END DO 


- AND. 


X$C_BUTTON2) THEN 





To draw 8-bit or 2-byte text, use the DRAW STRING, DRAW STRING 

16, DRAW IMAGE STRING, and DRAW IMAGE STRING 16 routines. 
DRAW STRING and DRAW STRING 16 display the foreground values of 
text only. DRAW IMAGE STRING and DRAW IMAGE STRING 16 display 
both foreground and background values. 


Example 8—2 illustrates drawing text with the DRAW STRING routine. 
The example modifies the sample program in Chapter 1 to draw shadow 


text. 


Example 8-2 Drawing Text Using the DRAW STRING Routine 


IF (EVENT.EVNT_TYPE .EQ. XSC_EXPOSE .AND. 
L. EVENT .EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. 
CALL X$CLEAR_ WINDOW (DPY, WINDOW_2) 

CALL X$SET_FOREGROUND (DPY, GC, 


WINDOW_2) THEN 


1 DEFINE COLOR(DPY, SCREEN, VISUAL, 3) ) 
CALL X$DRAW_STRING(DPY, WINDOW 2, GC, 

1 35, 75, MESSAGE (STATE) ) 
CALL XSSET_FOREGROUND (DPY, GC, 

1 DEFINE COLOR(DPY, SCREEN, VISUAL, 4) ) 
CALL XSDRAW_STRING(DPY, WINDOW_2, GC, 

ak 31, 71, MESSAGE (STATE) ) 

END IF 





(continued on next page) 
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Example 8-2 (Cont.) Drawing Text Using the DRAW STRING Routine 


IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON PRESS) THEN 
IF (EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_1) THEN 
STATE = 2 
CALL XSCLEAR_WINDOW(DPY, WINDOW_2) 
CALL XSSET_FOREGROUND (DPY, GC, 


aH DEFINE COLOR(DPY, SCREEN, VISUAL, 3)) 
CALL X$DRAW_STRING(DPY, WINDOW _2, GC, 

1 35, 75, MESSAGE (STATE) ) 
CALL X$SET_ FOREGROUND (DPY, GC, 

1 DEFINE COLOR(DPY, SCREEN, VISUAL, 4)) 
CALL XSDRAW_STRING(DPY, WINDOW_2, GC, 

1 31, 71, MESSAGE (STATE) ) 

ELSE 


Unmap and destroy windows 


aaa 


CALL X$UNMAP_WINDOW(DPY, WINDOW_1) 
CALL X$DESTROY_WINDOW(DPY, WINDOW_1) 
CALL X$CLOSE DISPLAY (DPY) 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
END IF 
END DO 


END 


The server refers to the following members of the GC data structure when 
writing text with DRAW TEXT, DRAW TEXT 16, DRAW STRING, and 


DRAW STRING 16: 

Function Plane mask 
Foreground Subwindow mode 
Stipple Font 

Background Tile 

Tile stipple x origin Tile stipple y origin 
Clip x origin Clip y origin 

Clip mask Fill style 


To draw both foreground and background values of text, use the DRAW 
IMAGE STRING and DRAW IMAGE STRING 16 routines. For example, 
the sample program uses the DRAW IMAGE routine to write the text 
“Click Here to Exit,” as follows: 


INTEGER*4 STATE !flag for text 
CHARACTER*19 MESSAGE (2) 
DATA MESSAGE /’Click here to exit ', ‘Click HERE to exit!’/ 


CALL X$DRAW_IMAGE STRING(DPY, WINDOW_2, GC, 
i 75, 75, MESSAGE (STATE) ) 
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The effect is first to fill a rectangle with the background defined in the 
graphics context and then to paint the text with the foreground pixel. The 
upper left corner of the filled rectangle is at 75,(75 — font ascent). The 
width of the rectangle is equal to the width of the string. The height of the 
rectangle is equal to font ascent + font descent. 


When drawing text in response to calls to DRAW IMAGE STRING and 
DRAW IMAGE STRING 16, the server ignores the function and fill style 
the client has defined in the graphics context. The value of the function 
member of the GC data structure is effectively the value specified by the 
constant x$c_gx_copy. The value of the fill style member is effectively 
the value specified by the constant x$c_fill_solid. 


The server refers to the following members of the GC data structure when 
writing text with DRAW IMAGE STRING and DRAW IMAGE STRING 16: 


Subwindow mode Plane mask 


Foreground Background 
Stipple Font 

Clip x origin Clip y origin 
Clip mask 
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9 Handling Events 


An event is a report of either a change in the state of a device (such as a 
mouse) or the execution of a routine called by a client. An event can be 
either unsolicited or solicited. Typically, unsolicited events are reports of 
keyboard or pointer activity. Solicited events are Xlib responses to calls by 
clients. 


Xlib reports events asynchronously. When any event occurs, Xlib processes 
the event and sends it to clients that have specified an interest in that 
type of event. 


This chapter describes the following concepts needed to manage events: 
¢ Event processing—An overview of types of events 


e Event type selection—A description of how clients can specify the types 
of events Xlib reports to them 


° Event handling—A description of handling specific types of events 





9.1 Event Processing 


Apart from errors, which Section 9.13 describes, Xlib events issue from 
operations on either windows or pixmaps. Most events result from 
operations associated with windows. The smallest window that contains 
the pointer when a window event occurs is the source window. 


Xlib searches the window hierarchy upward from the source window until 
one of the following applies: 


¢ Xlib finds a window that one or more clients has identified as 
interested in the event. This window is the event window. After 
Xlib locates an event window, it sends information about the event to 
appropriate clients. 


¢ Xlib finds a window whose X$L_SWDA_DO_NOT_PROPAGATE 
attribute has been set by a client. Setting this attribute specifies 
that Xlib should not notify ancestors of the window owned by the 
client of events occurring in the window and its children. For more 
information about the X$L_SWDA_DO_NOT_PROPAGATE attribute, 
see Chapter 3. 


¢ Xlib reaches the top of the window hierarchy without finding a window 
that a client has identified as interested in the event. In this case, the 
event is not sent. 


While there are many types of window events, events associated with 
pixmaps occur only when a client cannot compute a destination region 
because the source region is out of bounds (see Chapter 6 for a description 
of source and destination regions), When a client attempts an operation 
on an out of bounds pixmap region, Xlib puts the event on the event queue 
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and checks a list to determine if a client is interested in the event. Ifa 
client is interested, Xlib sends information to the client using an event 
data structure. 


Xlib can report 30 types of events related to keyboards, mice, windowing, 
and graphics operations. A flag identifies each type to facilitate referring 
to the event. Table 9-1 lists event types, grouped by category, and the 
flags that represent them. 


Table 9-1 Event Types 


Event Type Flag Name 


Keyboard Events 


Key press x$c_key_press 


Key release x$c_key_release 


Pointer Motion Events 


Button press x$c_button_press 
x$c_button_release 


x$c_motion_notify 


Button release 
Motion notify 


Window Crossing Events 


Enter notify 
Leave notify 


x$c_enter_notify 
x$c_leave_notify 


Input Focus Events 


Focus in x$c_focus_in 


Focus out x$c_focus_out 





Keymap State Event 


Keymap notify x$c_keymap_notify 


Exposure Events 





Expose x$c_expose 
x$c_graphics_expose 


x$c_no_expose 


Graphics expose 
No expose 
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Table 9-1 (Cont.) Event Types 


Event Type 


Data Structure Control Events 


Circulate request 
Configure request 
Map request 
Resize request 


Window State Events 


Circulate notify 
Configure notify 
Create notify 
Destroy notify 
Gravity notify 
Map notify 
Mapping notify 
Reparent notify 
Unmap notify 
Visibility notify 


Color Map State Events 


Color map notify 


Client Communication Events 


Client message 
Property notify 
Selection clear 
Selection notify 
Selection request 


Flag Name 


x$c_circulate_request 
x$c_configure_request 
x$c_map_request 
x$c_resize_request 


x$c_circulate_notify 
x$c_configure_notify 
x$c_create_notify 
x$c_destroy_notify 
x$c_gravity_notify 
x$c_map_notify 
x$c_mapping_notify 
x$c_reparent_notify 
x$c_unmap_notify 
x$c_visibility_notify 


x$c_colormap_notify 


x$c_client_message 
x$c_property_notify 
x$c_selection_clear 
x$c_selection_notify 
x$c_selection_request 


Every event type has a corresponding data structure that Xlib uses to pass 
information to clients. See the sections that describe handling specific 
event types for a description of the relevant event-specific data structures. 


Xlib includes the any event data structure, which clients can use to receive 
reports of any type of event. Figure 9-1 illustrates the data structure. 
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Figure 9-1 Any Event Data Structure 







; 
: 
: 

x$l_anyv_window 16 


Table 9~—2 describes members of the data structure. 


Table 9-2 Any Event Data Structure Members 


Member Name Contents 
X$L_ANYV_TYPE Type of event Xlib is reporting 
X$L_ANYV_SERIAL Number of the last request processed by the server 


X$L_ANYV_SEND_EVENT Value defined by the constant true if the event came 
from a SEND EVENT request 


X$A_ANYV_DISPLAY Display on which the event occurred 
X$L_ANYV_WINDOW Window in which the event occurred 





To enable clients to manage multiple types of events easily, Xlib also 
includes an event data structure, which is composed of the union 

of individual event data structures. Figure 9—2 illustrates the data 
structure. 


Figure 9-2 Event Data Structure 


i=) 


x$l_evnt_iype 


variable event data, depending upon x$l_evnt_type (124 bytes) 


128 





The X$L_EVNT_TYPE member specifies the type of event being reported. 
For descriptions of the other members of the event data structure, see the 
section that describes the specific event. 
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Selecting Event Types 


Xlib sends information about an event only to clients that have specified 
an interest in that event type. Clients use one of the following methods to 
indicate interest in event types: 


By calling the SELECT INPUT routine. SELECT INPUT indicates to 
Xlib which events to report. 


By specifying event masks when creating a window. 
By specifying event masks when changing window attributes. 


By specifying the graphics exposure mask when creating the graphics 
context. For more information about specifying a graphics exposure 
mask, see Chapter 4. 


Note that Xlib always reports client messages, mapping notifications, 
selection clearings, selection notifications, and selection requests. 


See the description of the SELECT INPUT routine in the VMS 
DECwindows Xlib Routines Reference Manual for restrictions on event 
reporting to multiple clients. 


Using the SELECT INPUT Routine 


Use the SELECT INPUT routine to specify the types of events Xlib reports 
to a client. Select event types by passing to Xlib one or more of the masks 
listed in Table 9-3. 


Table 9-3 Event Masks 


Event Mask 


x$m_button_motion 


x$m_button1_motion 
x$m_button2_motion 
x$m_button3_motion 
x$m_button4_motion 
x$m_button5_motion 
x$m_button_press 
x$m_button_release 
x$m_colormap_change 
x$m_enter_window 
x$m_exposure 


x$m_leave_window 


Event Reported (Event Type) 

At least one button on the pointing device is pressed while the pointer moves 
(x$c_motion_notify). 

Pointing device buiton 1 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 2 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 3 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 4 is pressed while the pointer moves (x$c_motion_notify). 
Pointing device button 5 is pressed while the pointer moves (x$c_button_press). 
Any pointing device button is pressed (x$c_button_press). 

Any pointing device button is released (x$c_button_release). 

A client installs, changes, or removes a color map (x$c_colormap_notify). 

The pointer enters a window (x$c_enter_notify). 


A window becomes visible, a graphics region cannot be computed, a graphics 
request exposes a region, or all source available and a no expose generated 
(x$c_expose, x$c_graphics_expose, x$c_graphics_noexpose). 


The pointer leaves a window (x$c_leave_notify). 
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Table 9-3 (Cont.) Event Masks 


Event Mask 


x$m_focus_change 
x$m_keymap_state 
x$m_key_press 
x$m_owner_grab_button 
x$m_pointer_motion 
x$m_pointer_motion_hint 


x$m_property_change 
x$m_structure_notify 


x$m_substructure_notify 


x$m_visibility_change 


Event Reported (Event Type) 


The keyboard focus changes (x$c_focus_in, x$c_focus_out). 
The key map changes (x$c_keymap_notify). 

A key is pressed or released (x$c_key_press, x$c_key_release). 
Not applicable. 

The pointer moves (x$c_motion_notify). 


Xlib is free to report only one pointer-motion event (x$c_motion_notify) until one of 
the following occurs: 


« Either the key or button state changes. 
+ The pointer leaves the window. 
* The client calls QUERY POINTER or GET MOTION EVENTS. 


A client changes a property (x$c_property_notify). 
One of the following operations occurs on a window: 


* Circulate (x$c_circulate_notify) 

* Configure (x$c_configure_notify) 
+ Destroy (x$¢_destroy_notify) 

* Move (x$c_gravity_notify) 

* Map (x$c_map_notify) 

« Reparent (x$c_reparent_notify) 
¢« Unmap (x$c_unmap_notify) 


One of the following operations occurs on the child of a window: 


* Circulate (x$c_circulate_notify) 

* Configure (x$c_configure_notify) 
* Create (x$c_create_notify) 

* Destroy (x$c_destroy_notify) 

* Move (x$c_gravity_notify) 

¢ Map (x$c_map_notify) 

* Reparent (x$c_reparent_notify) 
¢ Unmap (x$c_unmap_notify) 


The visibility of a window changes (x$c_visibility_notify). 
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The following illustrates using the SELECT INPUT routine: 


CALL XS$SELECT_INPUT(DPY, WINDOW, X$M_STRUCTURE_NOTIFY) 


Clients specify the x$m_structure_notify mask to indicate an interest in 
one or more of the following window operations (see Table 9—3): 


Circulating Configuring 
Destroying Reparenting 
Changing gravity Mapping and unmapping 


Handling Events 
9.2 Selecting Event Types 


9.2.2 Specifying Event Types When Creating a Window 


To specify event types when calling the CREATE WINDOW routine, 
use the method described in Section 3.2.2 for setting window attributes. 
Indicate the type of event Xlib reports to a client by doing the following: 


1 Set the X$L_SWDA_EVENT_MASK window attribute to one or more 
masks listed in Table 9-3. 


2 Specify the event mask flag in the value_mask argument of the 
CREATE WINDOW routine. 


Example 9-1 illustrates this method of selecting events. The program 
specifies that Xlib notify the client of a exposure events. 


Example 9-1 Selecting Event Types Using the CREATE WINDOW Routine 


INTEGER*4 WINDOW _1 


PARAMETER WINDOW _W = 400, WINDOW_H = 300 


Cc 

Cc Create the WINDOW_1 window 

c 
WINDOW_1X = (X$WIDTH_OF_SCREEN(SCREEN) - WINDOW_1W) / 2 
WINDOW_1Y = (X$HEIGHT OF SCREEN(SCREEN) - WINDOW_1H) / 2 
DEPTH = X$DEFAULT_DEPTH_OF_SCREEN (SCREEN) 
CALL X$DEFAULT_VISUAL_OF_SCREEN (SCREEN, VISUAL) 
ATTR_MASK = X$M_CW_EVENT MASK .OR. X$SM_CW_BACK PIXEL 

1 XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON_PRESS 
XSWDA.X$L_SWDA_BACKGROUND PIXEL = 
1 DEFINE COLOR(DPY, SCREEN, VISUAL, 1) 

e WINDOW_1 = X$CREATE WINDOW (DPY, 


1 X$ROOT_WINDOW_OF_ SCREEN (SCREEN) , 
1 WINDOW 1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 0, 
1 DEPTH, X$C_INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


@ Set the event mask of the set window attributes data structure to 
indicate interest in exposure events. 


@ The window attribute is referred to by ATTR_MASK, which specifies 
the attribute. 


9.2.3 Specifying Event Types When Changing Window Attributes 


To specify one or more event types when changing window attributes, 
use the method described in Section 3.6 for changing window attributes. 
Indicate an interest in event types by doing the following: 


1 Set the X$L_SWDA_EVENT_MASK window attribute to one or more 
masks listed in Table 9-3. 


2 Specify the event mask flag using the value_mask argument of the 
CHANGE WINDOW ATTRIBUTES routine. 
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9.3.1 
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ATTR_MASK 


The following illustrates this method: 


X$M_STRUCTURE_NOTIFY 


CALL X$CHANGE_WINDOW_ATTRIBUTES (DPY, WINDOW, ATTR_MASK, XSWA) 





Pointer Events 


Xlib reports pointer events to interested clients when the button on the 
pointing device is pressed or released, or when the pointer moves. 


This section describes how to handle the following pointer events: 
¢ Pressing a button on the pointing device 

¢ Releasing a button on the pointing device 

¢ Moving the pointing device 


The section also describes the button event and motion event data 
structures. 


Handling Button Presses and Releases 
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To receive event notification of button presses and releases, pass the 
window identifier and either the x$m_button_press or the x$m_button_ 
release mask when using the selection method described in Section 9.2. 


When a button is pressed, Xlib searches for ancestors of the event window 
from the root window down to determine whether or not a client has 
specified a passive grab, an exclusive interest in the button. If Xlib finds 
no passive grab, it starts an active grab, reserving the button for the 
sole use of the client receiving notification of the event. Xlib also sets the 
time of the last pointer grab to the current Xlib time. The effect is the 
same as calling the GRAB BUTTON routine with argument values listed 
in Table 9-4. 


Table 9-4 Values Used for Grabbing Buttons 


Argument Vaiue 

window_id Event window. 

event_mask Client pointer motion mask. 

pointer_mode The value specified by the constant x$c_grab_mode_async. 
keyboard_mode The value specified by the constant x$c_grab_mode_async. 
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Table 9-4 (Cont.) Values Used for Grabbing Buttons 








Argument Value 

owner_events True, if the owner has specified x$m_owner_grab_button. 
Otherwise, false. 

confine_to None. 

cursor None. 





Xlib terminates the grab automatically when the button is released. 
Clients can modify the active grab by calling the UNGRAB POINTER and 
CHANGE ACTIVE POINTER GRAB routines. 


Xlib uses the button event data structure to report button presses and 
releases. Figure 9-3 illustrates the data structure. 


Figure 9-3 Button Event Data Structure 
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Table 9-5 describes members of the button event data structure. 


Table 9-5 Button Event Data Structure Members 


Member Name 


X$L_BTEV_TYPE 


X$L_BTEV_SERIAL 
X$L_BTEV_SEND_EVENT 


X$A_BTEV_DISPLAY 
X$L_BTEV_WINDOW 
X$L_BTEV_ROOT 
X$L_BTEV_SUBWINDOW 
X$L_BTEV_TIME 
X$L_BTEV_X 


X$L_BTEV_Y 


X$L_BTEV_X_ROOT 
X$L_BTEV_Y_ROOT 
X$L_BTEV_STATE 


X$L_BTEV_BUTTON 


X$L_BTEV_SAME_SCREEN 


Contents 

Type of event reported. The event type can be either x$c_button_press or 
x$c_button_release. 

Number of the last request processed by the server. 


Value defined by the constant true if the event came from a SEND EVENT 
request. 


Display on which the event occurred. 

Event window. 

Root window in which the event occurred. 
Source window in which the event occurred. 
Time in milliseconds at which the event occurred. 


The x value of the pointer coordinates in the source window at the time the 
event occurred. 


The y value of the pointer coordinates in the source window at the time the 
event occurred. 


The x value of the pointer coordinates, relative to the root window. 
The y value of the pointer coordinates, relative to the root window. 


State of the button just prior to the event. Xlib can set this member to the 
bitwise OR of one or more of the following masks: 


x$m_button1 x$m_button2 
x$m_button3 x$m_button4 
x$m_button5 x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 


Buttons that changed state. Xli can set this member to one of the 
following values: 


x$c_button1 x$c_button2 
x$c_button3 x$c_button4 
x$c_button5 


Indicates whether or not the event window is on the same screen as the 
root window. 





Example 9-2 illustrates the button press event handling routine of the 
sample program described in Chapter 1. 
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Example 9-2 Handling Button Presses 





IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS) THEN 
IF (EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_1) THEN 


STATE = 2 
CALL X$DRAW_IMAGE STRING(DPY, WINDOW_2, GC, 
1 75, 75, MESSAGE (STATE) ) 
ELSE 


CALL XSUNMAP_WINDOW(DPY, WINDOW_1) 
CALL X$DESTROY WINDOW (DPY, WINDOW_1) 
CALL X$CLOSE_DISPLAY (DPY) 
CALL SYSSEXIT(%VAL (1) ) 
END IF 
END IF 


The program calls shutdown routines when the user presses the mouse 
button in WINDOW_2. When creating WINDOW_1 and WINDOW_2, the 
client indicated an interest in exposures and button presses by setting the 
event mask field of the set window attributes data structure, as follows: 


RECORD /XSSET_WIN ATTRIBUTES/ XSWDA 


XSWDA.X$L_SWDA_EVENT_MASK = X$M_CW_EVENT MASK 
-OR. X$M_CW_BUTTON PRESS 


For more information about selecting event types, see Section 9.2. 


9.3.2 Handling Pointer Motion 


To only receive pointer motion events when a specified button is pressed, 
pass the window identifier and one of the following masks when using the 
selection method described in Section 9.2: 


x$m_button_motion x$m_button1_motion 

x$m_button2_motion x$m_button3_motion 

x$m_button4_motion x$m_button5_motion 

Xlib reports pointer motion events to interested clients whenever the 
pointer moves and the movement begins and ends in the window. Spatial 
and temporal resolution of the events is not guaranteed, but clients are 
assured they will receive at least one event when the pointer moves and 


then rests. Figure 9—4 illustrates the data structure Xlib uses to report 
these events. 
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Figure 9-4 Motion Event Data Structure 

































x$l_mtev_type 0 
: 
x$a_mtev_display 12 
: 
: 
x$l_mtev_subwindow 24 
: 
: 
: 
: 
: 
x$l_mtev_state 48 
= x$l_mtev_same_screen x$b_mtev_is_hint 52 
x$l_mtev_same_screen : 
Table 9-6 describes members of the data structure. 
Table 9-6 Motion Event Data Structure Members 
Member Name Contents 
X$L_MTEV_TYPE Type of event reported. The member can have only ihe value specified by the 
constant x$c_motion_notity. 
X$A_MTEV_DISPLAY Display on which the event occurred. 
X$L_MTEV_SERIAL Number of the last request processed by the server. 
X$L_MTEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$L_MTEV_WINDOW Event window. 
X$L_MTEV_ROOT Root window in which the event occurred. 
X$L_MTEV_SUBWINDOW Source window in which the event occurred. 
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Table 9-6 (Cont.) Motion Event Data Structure Members 


Member Name 


Contenis 





X$L_MTEV_TIME 
X$L_MTEV_X 
X$L_MTEV_Y 
X$L_MTEV_X_ROOT 
X$L_MTEV_Y_ROOT 
X$L_MTEV_STATE 


X$B_MTEV_IS_HINT 


X$L_MTEV_SAME_SCREEN 


Time in milliseconds at which the event occurred. 

The x value of the pointer coordinates in the source window. 

The y value of the pointer coordinates in the source window. 

The x value of the pointer coordinates relative to the root window. 
The y value of the pointer coordinates relative to the root window. 


State of the button just prior to the event. Xlib can set this member to the 
bitwise OR of one or more of the following masks: 


x$m_button1 x$m_bution2 
x$m_button3 x$m_button4 
x$m_button5 x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 


Indicates that motion hints are active. No other events reported until pointer 
moves out of window. 


Indicates whether or not the event window is on the same screen as the root 
window. 





Example 9-3 illustrates pointer motion event handling. 


Example 9-3 Handling Pointer Motion 





IF (EVENT.EVNT TYPE .EQ. XSC_MOTION_NOTIFY) THEN 


x 
Y 


EVENT .EVNT_MOTION.X$L_MTEV_X 
EVENT .EVNT_MOTION.X$L_MTEV_Y 


CALL X$FILL RECTANGLE (DPY, WINDOW, GC, X, Y, WIDTH, LENGTH) 


ENDIF 





Each time the pointer moves, the program draws a filled rectangle at the 
resulting x and y coordinates. 


To receive pointer motion events, the client specifies the x$c_motion_ 
notify flag when removing events from the queue. The client indicated 
an interest in pointer motion events when creating window WINDOW, as 
follows: 


XSWDA.XSL SWDA_EVENT MASK = X$M_EXPOSURE 
1 .OR. XSM_BUTTON_PRESS 
1 .OR. X$M_POINTER_MOTION 


XSWDA.X$L_SWDA_BACKGROUND_PIXEL = 
1 DEFINE _COLOR(DPY, SCREEN, VISUAL, 1) 
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WINDOW = X$CREATE WINDOW (DPY, 

1 X$ROOT_WINDOW_OF_SCREEN (SCREEN) , 

1 WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H, 0, 

1 DEPTH, X$C_INPUT OUTPUT, VISUAL, ATTR_MASK, XSWDA) 


The server reports pointer movement. Xlib records the resulting position 
of the pointer in a motion data structure, one of the event structures that 
constitute the event structure. The client determines the origin of the 
filled rectangle it draws by referring to the motion event data structure x 
and y members. 





Key Events 


Xlib reports key press and key release events to interested clients. To 
receive event notification of key presses and releases, pass the window 
identifier and either the x$m_key_press mask or the x$m_key_release 
mask when using the selection method described in Section 9.2. 


Xlib uses a key event data structure to report key presses and releases to 
interested clients whenever any key changes state, even when the key is 
mapped to modifier bits. 


Figure 9-5 illustrates the data structure. 
Figure 9-5 Key Event Data Structure 



















; 
: 
2 
: 
: 
: 

x$l_kyev_time 28 
: 
: 
: 
“ 
: 
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Figure 9-5 (Cont.) Key Event Data Structure 














82 
: 
Table 9—7 describes members of the data structure. 

Table 9-7 Key Event Data Structure Members 
Member Name Contents 
X$L_KYEV_TYPE Value defined by either the x$c_key_press or the x$c_key_release constant. 
X$L_KYEV_SERIAL Number of the last event processed by the server. 
X$L_KYEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$A_KYEV_DISPLAY Display on which the event occurred. 
X$L_KYEV_WINDOW Event window. 
X$L_KYEV_ROOT Root window on which the event occurred. 
X$L_KYEV_SUBWINDOW Source window of the event. 
X$L_KYEV_TIME Time in milliseconds at which the key event occurred. 
X$L_KYEV_X The x value of the pointer coordinates in the source window. 
X$L_KYEV_Y The y value of the pointer coordinates in the source window. 
X$L_KYEV_X_ROOT The x value of the pointer coordinates relative to the root window. 
X$L_KYEV_Y_ROOT The y value of the pointer coordinates relative to the root window. 
X$L_KYEV_STATE State of the key just prior to the key event. Xlib can set this member to the 
bitwise OR of the following states: 
x$m_shift x$m_lock 
x$m_control x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 
X$L_KYEV_KEYCODE An arbitrary but unique representation of the key that generated the event. 
X$L_KYEV_SAME_SCREEN Indicates whether the event window is on the same screen as the root window. 


Window Entries and Exits 


Xlib reports window entries and exits to interested clients when one of the 
following occurs: 


¢ .The pointer moves into or out of a window due to either pointer 
movement or to a change in window hierarchy. This is normal window 
entry and exit. 


¢ Accient calls WARP POINTER, which moves the pointer to any 
specified point on the screen. 
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e A client calls CHANGE ACTIVE POINTER GRAB, GRAB 
KEYBOARD, GRAB POINTER, or UNGRAB POINTER. This is 
pseudomotion, which simulates window entry or exit without actual 
pointer movement. 


To receive event notification of window entries and exits, pass the window 
identifier and either the x$m_enter_window mask or the x$m_leave_ 
window mask when using the selection method described in Section 9.2. 


Xlib uses the crossing event data structure to report window entries and 
exits. Figure 9-6 illustrates the data structure. 


Figure 9-6 Crossing Event Data Structure 


















; 
; 
: 
: 
: 
: 
: 
: 
: 
: 
: 
: 

x$l_crev_detail 52 
: 
: 
: 
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Table 9-8 describes members of the data structure. 


Table 9-8 Crossing Event Data Structure Members 


Member Name 


X$L_CREV_TYPE 


X$L_CREV_SERIAL 
X$L_CREV_SEND_EVENT 


X$A_CREV_DISPLAY 
X$L_CREV_WINDOW 
X$L_CREV_ROOT 
X$L_CREV_SUBWINDOW 
X$L_CREV_TIME 
X$L_CREV_X 
X$L_CREV_Y 
X$L_CREV_X_ROOT 
X$L_CREV_Y_ROOT 
X$L_CREV_MODE 


X$L_CREV_DETAIL 


X$L_CREV_SAME_SCREEN 


X$L_CREV_FOCUS 


X$L_CREV_STATE 


Contents 

Value defined by either the x$c_enter_notify or the x$c_leave_notify 
constant. 

Number of the last request processed by the server. 


Value defined by the constant true if the event came from a SEND EVENT 
request. 


Display on which the event occurred. 

Event window. 

Root window in which the event occurred. 

Source window in which the event occurred. 

Time in milliseconds at which the event occurred. 

The x value of the pointer coordinates in the source window. 

The y value of the pointer coordinates in the source window. 

The x value of the pointer coordinates relative to the root window. 
The y value of the pointer coordinates relative to the root window. 


Indicates whether the event is normal or pseudomotion. Xlib can set this 
member to the value specified by x$c_notify_normal, x$c_notify_grab, and 
x$c_notify_ungrab. See Section 9.5.1 and Section 9.5.2 for descriptions of 
normal and pseudomotion events. 

Indicates which windows Xlib notifies of the window entry or exit event. 
Xlib can specify in this member one of the following constants: 
x$c_notify_ancestor x$c_notify_virtual 

x$c_notify_inferior x$c_notify_nonlinear 
x$c_notify_nonlinear_virtual 


Indicates whether or not the event window is on the same screen as the 
root window. 


Specifies whether the event window or an inferior is the focus window. If 
true, the event window is the focus window. If false, an inferior is the focus 
window. 


State of buttons and keys just prior to the event. Xlib can return the 
following constants: 


x$m_button1 x$m_button2 
x$m_button3 x$m_button4 
x$m_button5 x$m_mod1 
x$m_mod2 x$m_mod3 
x$m_mod4 x$m_mod5 
x$m_shift x$m_control 
x$m_lock 
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Normal Window Entries and Exits 


A normal window entry or exit event occurs when the pointer moves from 
one window to another due to either a change in window hierarchy or the 
movement of the pointer. In either case, Xlib sets the X$L_CREV_MODE 
member of the crossing event data structure to the constant x$c_notify_ 
normal. 


If the pointer leaves or enters a window as a result of one of the following 
changes in window hierarchy, Xlib reports the event after reporting the 
hierarchy event: 


Mapping Unmapping 
Configuring Circulating 
Changing gravity 


Xlib can report a window entry or exit event caused by changes in focus, 
visibility, and exposure either before or after reporting these events. 


Table 9-9 describes the events Xlib reports when the pointer moves from 
window A to window B as a result of normal window entry or exit. 


Table 9-9 Normal Window Entry and Exit Event Reporting 


Relationship of Windows 


Events Reported 


Window A is inferior to window B A leave notify event on window A with the X$L_CREV_DETAIL 


member of the crossing event data structure set to the constant 
x$c_notify_ancestor 


A leave notify event on each window between window A and 
window B exclusive, with the X$L_CREV_DETAIL member of each 
crossing event data structure set to the constant x$c_notify_virtual 


An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_inferior 


Window B is inferior of window A A leave notify event on window A with the X$L_CREV_DETAIL 


member of the crossing event data structure set to the constant 
x$c_notify_inferior 

An enter notify event on each window between window A and 
window B exclusive with the X$L_CREV_DETAIL member of each 
crossing event data structure set to the constant x$c_notify_virtual 


An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_ancestor 
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Table 9-9 (Cont.) Normal Window Entry and Exit Event Reporting 


Relationship of Windows 


Events Reported 





Window C is the least common ancestor of 
AandB 


Window A and window B are on different 
screens 


A leave notify event on window A with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 


A leave notify event on each window between window A and 
window C exclusive with the X$L_CREV_DETAIL member of the 
crossing event data structure set to the constant 
x$c_notify_nonlinear_virtual 


An enter notify event on each window between window C and 
window B exclusive with the X$L_CREV_DETAIL member of each 
crossing event data structure set to the constant 
x$c_notify_nonlinear_virtual 


An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 


A leave notify event on window A with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 


If window A is not a root window, a leave notify event on each 
window above window A up to and including its root, with the 
X$L_CREV_DETAIL member of each crossing event data structure 
set to the constant x$c_notify_nonlinear_virtual 


If window B is not a root, an entry notify event on each window 
from window B's root down to but not including window B, with the 
X$L_CREV_DETAIL member of the crossing event data structure 
set to the constant x$c_notify_nonlinear_virtual 


An enter notify event on window B with the X$L_CREV_DETAIL 
member of the crossing event data structure set to the constant 
x$c_notify_nonlinear 





Example 9-4 illustrates window entry and exit event handling. The 
program changes the color of a window when the pointer enters or leaves 


the window. 


Figure 9-7 shows the resulting output. 
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Example 9-4 Handling Window Entries and Exits 


aaa 
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Create windows WINDOW, SUB1, SUB2, 


SUB3, 


and SUB4 on display DPY. 


Position of WINDOW is: x = 100,y = 100 


PARAMETER WINDOW _W = 600, WINDOW_H = 600, 


1 


BREE 


SUB_ WIDTH = 120, SUB_HEIGHT= 120, 
SUB1_X = 120, SUB1_Y = 120, 


SUB2_X = 360, SUB2_Y = 120, 
SUB3_X = 120, SUB3_Y = 360, 
SUB4_X = 360, SUB4_Y = 360 


IF (EVENT.EVNT_ TYPE .EQ. X$C_ENTER NOTIFY) THEN 
CROSS_WINDOW = EVENT. EVNT_CROSSING.X$L_CREV_WINDOW 
CALL XS$SET_WINDOW_BACKGROUND (DPY, CROSS WINDOW, 
DEFINE COLOR(DPY, SCREEN, VISUAL, 3)) 
CALL X$CLEAR_AREA(DPY, CROSS WINDOW, 0, 0, SUB_WIDTH, 
SUB_HEIGHT, 0) 





END IF 


IF (EVENT.EVNT TYPE .EQ. XSC_LEAVE NOTIFY) THEN 
CROSS_WINDOW = EVENT.EVNT_CROSSING.X$L_CREV_WINDOW 
CALL X$SET_WINDOW BACKGROUND (DPY, CROSS WINDOW, 
DEFINE COLOR(DPY, SCREEN, VISUAL, 2)) 
CALL X$CLEAR_AREA(DPY, CROSS WINDOW, 0, 0, SUB _WIDTH, 
SUB_HEIGHT, 0) 
END IF 


@ Xlib gives the identifier of the window that the pointer cursor has 
entered in the crossing event data structure window field. The 
program uses the identifier to define the window background and 
clear the window. 


@ The CLEAR AREA routine clears the window and repaints it with the 
newly defined window background. 
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Figure 9-7 Window Entries and Exits 


Window Entry and Exit 


Subwindows turn gray when pointer cursor is in them. 


To exit, click MB2. 





ZK-0153A-GE 


9.5.2 Pseudomotion Window Entries and Exits 


Pseudomotion window entry and exit events occur when the pointer cursor 
moves from one window to another due to activating or deactivating a 
pointer grab. 


Xlib reports a pseudomotion window entry if a client grabs the pointer, 
causing the pointer cursor to change from one window to another even 
though the pointer cursor has not moved. For example, if the pointer 
cursor is in window A and a client maps window B over window A, the 
pointer cursor changes from being in window A to being in window B. If 
possible, the pointer cursor remains in the same position on the screen. 
When the placement of the two windows prevents the pointer cursor from 
maintaining the same position, the pointer cursor moves to the location 
closest to its original position. 
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9.5 Window Entries and Exits 


Clients can grab pointers actively by calling the GRAB POINTER routine 
or passively by calling the GRAB BUTTON routine. Whether the grab is 
active or passive, Xlib sets the following members of the crossing event 
data structure to the indicated constants after the pointer cursor moves 
from one window to another: 


¢ X$L_CREV_TYPE member—x$c_enter_notify 
¢ X$L_CREV_MODE member—x$c_notify_grab 


When a client passively grabs the pointer by calling the GRAB BUTTON 
routine, Xlib reports a button press event after reporting the pointer grab. 


Xlib reports a pseudomotion window exit when a client deactivates a 
pointer grab, causing the pointer cursor to change from one window to 
another even though the pointer cursor has not moved. 


Clients can deactivate pointer grabs either actively by calling the 
UNGRAB POINTER routine or passively by calling the UNGRAB 
BUTTON routine. Whether deactivating the grab is active or passive, 
Xlib sets the following members of the crossing event data structure to 
the indicated constants after the pointer cursor moves from one window to 
another: 


¢ X$L_CREV_TYPE member—x$c_leave_notify 
* X$L_CREV_MODE member—x$c_notify_ungrab 
When a client passively deactivates a pointer grab by calling the UNGRAB 


BUTTON routine, Xlib reports a button release event before reporting that 
the pointer has been released. 





9.6 Input Focus Events 
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Input focus defines the window to which Xlib sends keyboard input. The 
keyboard is always attached to some window. Typically, keyboard input 
goes to either the root window or to a window at the top of the stack called 
the focus window. The focus window and the position of the pointer 
determine the window that receives keyboard input. 


When the keyboard input focus changes from one window to another, Xlib 
reports a focus out event and a focus in event. The window that loses the 
input focus receives the focus out event. The window that gains the focus 
receives a focus in event. Additionally, Xlib notifies other windows in the 
hierarchy of focus in and focus out events. 


To receive notification of input focus events, pass the window identifier and 
the x$m_focus_change mask when using the selection method described 
in Section 9.2 


Xlib uses the focus change event data structure to report keyboard input 
focus events. Figure 9-8 illustrates the data structure. 


Handling Events 
9.6 Input Focus Events 


Figure 9-8 Focus Change Event Data Structure 
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Table 9-10 describes members of the data structure. 


Table 9-10 Focus Change Event Data Structure Members 








Member Name Contents 

X$L_FCEV_TYPE Value defined by either the x$c_focus_in or x$c_focus_out constant. 

X$L_FCEV_SERIAL Number of the last request processed by the server. 

X$L_FCEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 

X$A_FCEV_DISPLAY Display on which the event occurred. 

X$L_FCEV_WINDOW Event window. 

X$L_FCEV_MODE Specifies whether the event is the result of normal keyboard input, keyboard 


input after a client has grabbed the keyboard, keyboard input at the time 
the client activates a keyboard grab, or keyboard input at the time the client 
deactivates a keyboard grab. 


Xlib can set this field to one of the following constants: 
x$c_notify_normal x$c_notify_while_grabbed 
x$c_notify_grab x$c_notify_ungrab 


See Section 9.6.1 and Section 9.6.2 for descriptions of processing input focus 
events in each of these conditions. 


X$L_FCEV_DETAIL Specifies which windows and pointers Xlib notifies of the input focus change. 
Xlib can set this field to one of the following constants: 
x$c_notify_ancestor x$c_notify_virtual 
x$c_notify_inferior x$c_notify_nonlinear 
x$c_notify_nonlinear_virtual x$c_notify_pointer 
x$c_notify_pointer_root x$c_notify_detail_none 
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9.6.1 


Handling Events 


9.6 Input Focus Events 


Normal Keyboard Input Focus 


A normal keyboard input focus event occurs when keyboard input focus 
changes, and the keyboard has not been or is not being grabbed. When 
a normal keyboard input focus event occurs, Xlib sets the X$L_FCEV_ 

MODE member of the focus change event data structure to the constant 


x$c_notify_normal. 


Table 9-11 lists focus change events reported when window A and window 
B are on the same screen, the focus changes from window A to window B, 


and the pointer cursor is in window P. 


Table 9-11 Effect of Focus Changes: Windows on Same Screen 


Window A Inferior to Window B 


Window 


Window A 
Window B 
Window P 


Other windows 


Event Reported 


Focus out event 
Focus in event 


Focus in event on each window between 
window B and window P including P if 
window P is an inferior of window B, but 


window P is not window A or an inferior of A 


Focus out event on each window between 
window A and window B exclusive 


Window B Inferior to Window A 


Window 


Window A 
Window B 
Window P 


Other windows 
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Event Reported 


Focus out event 
Focus in event 


Focus out event on each window between 
window P and window A if window P is an 
inferior of window A, but window P is not 
window A or an inferior or ancestor of B 


Focus in event on each window between 
window A and window B exclusive 


Value of X$L_FCEV_DETAIL 


x$c_notify_ancestor 
x$c_notify_inferior 
x$c_notify_inferior 


x$c_notify_virtual 


Value of X$L_FCEV_DETAIL 


x$c_notify_inferior 
x$c_notify_ancestor 
x$c_notify_pointer 


x$c_notify_virtual 


Table 9-12 lists focus change events reported when the pointer cursor 
moves from window A to window B and window C is their least common 
ancestor. The pointer cursor is in window P. 


Handling Events 
9.6 Input Focus Events 


Table 9-12 Focus Changes Caused by Pointer Movement 





Pointer Moves from Window A to Window B 


Window Event Reported Value of X$L_FCEV_DETAIL 
Window A Focus out event x$c_notify_nonlinear 

Window B Focus in event x$c_notify_nonlinear 

Window P If window P is an inferior of window A, but x$c_notify_pointer 


window P is not window A or an inferior 
or ancestor of B, a focus out event on 
each window from window P up to but not 
including window A 


If window P is an inferior of window B, x$c_notify_pointer 
a focus in event on each window below 
window B down to and including window P 


Other windows Focus out event on each window between x$c_notify_nonlinear_virtual 
window A and window C exclusive 
Focus in event on each window between x$c_notify_nonlinear_virtual 


window C and window B exclusive 


Table 9-13 lists focus change events reported when window A and window 
B are on different screens and the focus changes from window A to window 
B. The pointer cursor is in window P. 


Table 9-13 Effect of Focus Changes: Windows on Different Screens 


Focus Changes from Window A to Window B 





Window Event Reported Value of X$L_FCEV_DETAIL 
Window A Focus out event x$c_notify_nonlinear 

Window B Focus in event x$c_notify_nonlinear 

Window P If window P is an inferior of window A, x$c_notify_pointer 


a focus out event on each window from 
window P up to but not including window A 


If window P is an inferior of window B, x$c_notify_pointer 
a focus in event on each window below 
window B down to and including window P 


Other windows lf window A is not a root window, a focus x$c_notify_nonlinear_virtual 
out event on each window above window A 
up to and including its root 
If window B is not a root window, a focus in x$c_notify_nonlinear_virtual 
event on each window from the root window 
of B down to but not including B 


Table 9-14 lists focus change events reported when the focus changes 
between window A and the pointer window, or when the focus is set to 
none (no focus). 
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9.6 Input Focus Events 


Table 9-14 Pointer Window and No Focus Changes 


Focus Changes from Window A to Pointer Window or to No Focus 


Window 


Window A 
All root windows 


Window P 


Other windows 


Event Reported 


Focus out event 
Focus in event 


If window P is an inferior of window A, 


a focus out event on each window from 
window P up to but not including window A 


lf window A is not a root window, a focus 
out event on each window above window A 


up to and including its root 


If the new focus is the window under the 
pointer, a focus in event on each window 
from the root of window P down to and 


including window P 


Value of X$L_FCEV_DETAIL 


x$c_notify_nonlinear 


x$c_notify_pointer_root or x$c_notify_ 
detail_none 


x$c_notify_pointer 


x$c_notify_nonlinear_virtual 


x$c_notify_pointer_root 





Focus Changes from Pointer Window or No Focus to Window A 


Window 


Window A 
All root windows 


Window P 


Other windows 
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Event Reported 


Focus in event 
Focus out event 


If window P is an inferior of window A, 


a focus in event on each window below 


window A down to and including P 
Focus out event on each window from 


window P up to and including the root of P 


Focus out event on each window from 


window P up to and including the root of P 


If window A is not a root window, a focus 
in event on each window from the root of 


window A down to but not including A 


Value of X$L_FCEV_DETAIL 


x$c_notify_nonlinear 


x$c_notify_pointer_root or x$c_notify_ 
detail_none 


x$c_notify_pointer 


x$c_notify_pointer_root 
x$c_notify_pointer_root 


x$c_notify_nonlinear_virtual 


(continued on next page) 
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Table 9-14 (Cont.) Pointer Window and No Focus Changes 


Focus Changes from Pointer Window to No Focus or from No Focus 
to Pointer Window 


Window Event Reported Value of X$L_FCEV_DETAIL 

All root windows Focus out event x$c_notify_pointer_root or x$c_notify_ 
detail_none 

Old focus window If the old focus was the window under the x$c_notify_pointer_root 


pointer, a focus out event on each window 
from window P up to and including the root 
of P 
New focus window If the new focus is the window under the x$c_notify_pointer_root 
pointer, a focus in event on each window 
from the root of P down to and including P 


Keyboard Input Focus Changes Caused by Grabs 


When a keyboard focus event occurs because a client activates a grab, 
Xlib sets the X$L_FCEV_MOVE member of the focus change event data 
structure to the constant x$c_notify_grab. 


When a keyboard focus event occurs because a client deactivates a grab, 
Xlib sets the X$L_FCEV_MOVE member of the focus change event data 
structure to the constant x$e_notify_ungrab. 





Key Map State Events 


Xlib reports changes in the state of the key map immediately after every 
enter notify and focus in event. 


To receive notification of key map state events, pass the window identifier 
and the x$m_keymap_state mask when using the selection method 
described in Section 9.2. 


Xlib uses the keymap event data structure to report changes in the key 
map state. Figure 9-9 illustrates the data structure. 


Figure 9-9 Keymap Event Data Structure 
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9.8.1 


Handling Events 
9.7 Key Map State Events 


Figure 9-9 (Cont.) Keymap Event Data Structure 


i ee a, 


x$b_kmev_key_vector (32 bytes) 
| | 52 


Table 9-15 describes members of the data structure. 


Table 9-15 Keymap Event Data Siructure Members 


Member Name Contents 

X$L_KMEV_TYPE Value defined by the x$c_keymap_notify constant. 

X$L_KMEV_SERIAL Number of the last request processed by the 
server. 

X$L_KMEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_KMEV_DISPLAY Display on which the event occurred. 

X$L_KMEV_WINDOW Event window. 

X$B_KMEV_KEY_VECTOR Bit vector of the keyboard. Each one bit indicates 


that the corresponding key is currently pressed. 
Byte N contains the bits for keys 8N to 8N+7 with 
the least significant bit representing key 8N. 





Exposure Events 


Xlib reports an exposure event when one of the following conditions occurs: 
¢ A formerly obscured window or window region becomes visible. 
¢ A destination region cannot be computed. 


e¢ A graphics request exposes one or more regions. 


This section describes how to handle window exposures and graphics 
exposures. 


Handling Window Exposures 
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A window exposure occurs when a formerly obscured window becomes 
visible again. Because Xlib does not guarantee to preserve the contents of 
regions when windows are obscured or reconfigured, clients are responsible 
for restoring the contents of the exposed window. 


To receive notification of window exposure events, pass the window 
identifier and the x$m_exposure mask when using the selection 
method described in Section 9.2. Xlib notifies clients of window exposures 
using the expose event data structure. Figure 9-10 illustrates the data 
structure. 


Handling Events 
9.8 Exposure Events 


Figure 9-10 Expose Event Data Structure 










Table 9-16 describes members of the data structure. 
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Table 9-16 Expose Event Data Structure Members 


Member Name Contents 

X$L_EXEV_TYPE Value defined by the x$c_expose constant. 

X$L_EXEV_SERIAL Number of the last request processed by the 
server. 

X$L_EXEV_SEND_ EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_EXEV_DISPLAY Display on which the event occurred. 

X$L_EXEV_WINDOW Event window. 

X$L_EXEV_X The x value of the coordinates that define the 


upper left corner of the exposed region. The 
coordinates are relative to the origin of the 
drawable. 


X$L_EXEV_Y The y value of the coordinates that define the 
upper left corner of the exposed region. The 
coordinates are relative to the origin of the 
drawable. 


(continued on next page) 
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Handling Events 
9.8 Exposure Events 


Table 9-16 (Cont.) Expose Event Data Structure Members 


Member Name Contenis 

X$L_EXEV_WIDTH Width of the exposed region. 
X$L_EXEV_HEIGHT Height of the exposed region. 
X$L_EXEV_COUNT Number of exposure events that are to follow. If 


Xlib sets the count to zero, no more exposure 
events follow for this window. 


Clients that do not optimize redisplay by 
distinguishing between subareas of its windows 
can ignore all exposure events with nonzero 
counts and perform full redisplays on events with 
zero counts. 


The following fragment from the sample program in Chapter 1 illustrates 
window exposure event handling: 


IF (EVENT.EVNT_TYPE .EQ. XSC_EXPOSE .AND. 
EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_2) THEN 
CALL X$CLEAR_WINDOW(DPY, WINDOW_2) 

CALL X$DRAW_IMAGE STRING(DPY, WINDOW_2, GC, 


75, 75, ‘Click here to exit’) 


The program checks exposure events to verify that the server has mapped 
the second window. After the window is mapped, the program writes text 
into it. 


9.8.2 Handling Graphics Exposures 
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Xlib reports graphics exposures when one of the following conditions 
occurs: 


¢ A destination region could not be computed due to an obscured or out 
of bounds source region. For information about destination and source 
regions, see Chapter 6. 


¢ A graphics request exposes one or more regions. If the request exposes 
more than one region, Xlib reports them continuously. 


Instead of using the SELECT INPUT routine to indicate an interest 

in graphics exposure events, assign a value of true to the X$L_GCVL_ 
GRAPHICS_EXPOSURES member of the GC values data structure. 
Clients can set the value to true at the time they create a graphics context. 
If a graphics context exists, use the SET GRAPHICS EXPOSURES 
routine to set the value of the field. For information about creating a 
graphics context and using the SET GRAPHICS EXPOSURES routine, see 
Chapter 4. 


Handling Events 
9.8 Exposure Events 


Xlib uses the graphics expose event data structure to report graphics 
exposures. Figure 9-11 illustrates the data structure. 


Figure 9-11 Graphics Expose Event Data Structure 





















x$a_geev_display 


Table 9-17 describes members of the data structure. 
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Table 9-17 Graphics Expose Event Data Structure Members 


Member Name Contents 

X$L_GEEV_TYPE Value defined by the constant x$c_graphics_ 
expose. 

X$L_GEEV_SERIAL Number of the last request processed by the 
server. 

X$L_GEEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$L_GEEV_DISPLAY Display on which the event occurred. 

X$L_GEEV_DRAWABLE Window or pixmap reporting the event. 


(continued on next page) 
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Handling Events 
9.8 Exposure Events 


Table 9-17 (Cont.) Graphics Expose Event Data Structure Members 





Member Name Contents 


X$L_GEEV_X The x value of the coordinates that define the 
upper left corner of the exposed region. The 
coordinates are relative to the origin of the 
drawable. 


X$L_GEEV_Y The y value of the coordinates that define the 
upper left corner of the region that is exposed. 
The coordinates are relative to the origin of the 


drawable. 
X$L_GEEV_WIDTH Width of the exposed region. 
X$L_GEEV_HEIGHT Height of the exposed region. 
X$L_GEEV_COUNT Number of exposure events that are to follow. If 


Xlib sets the count to zero, no more exposure 
events follow for this window. 


X$L_GEEV_MAJOR_CODE Indicates whether the graphics request was a copy 
area or copy plane. 
X$L_GEEV_MINOR_CODE The value zero. Reserved for use by extensions. 


Xlib uses the no expose event data structure to report when a graphics 
request that might have produced an exposure did not. Figure 9-12 
illustrates the data structure. 


Figure 9-12 No Expose Event Data Structure 








; 
: 
: 
: 

x$i_neev_major_code 20 
: 
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9.8 Exposure Events 


Table 9-18 describes members of the no expose event data structure. 


Table 9-18 No Expose Event Data Structure Members 


Member Name 


X$L_NEEV_TYPE 
X$L_NEEV_SERIAL 


X$L_NEEV_SEND_EVENT 


X$A_NEEV_DISPLAY 
X$L_NEEV_DRAWABLE 
X$L_NEEV_MAJOR_CODE 


X$L_NEEV_MINOR_CODE 


Contents 


Value defined by the constant x$c_no_expose. 


Number of the last request processed by the 
server. 


Value defined by the constant true if the event 
came from a SEND EVENT request. 


Display on which the event occurred. 
Window or pixmap reporting the event. 


Indicates whether the graphics request was a copy 
area or a copy plane. 


The value zero. Reserved for use by extensions. 


Example 9-5 illustrates handling graphics exposure events. The program 
checks for graphics exposures and no exposures to scroll up a window. 


Figure 9-13 shows the resulting output of the program. 


Example 9-5 Handling Graphics Exposures 





INTEGER*4 X, Y 
INTEGER*4 PX, PY 
INTEGER*4 WIDTH, HEIGHT 
INTEGER*4 BUTTON _IS DOWN 
INTEGER*4 VY 


Handle events 


aaa 


DO WHILE (.TRUE.) 





(continued on next page) 
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Example 9-5 (Cont.) Handling Graphics Exposures 





CALL X$NEXT_EVENT(DPY, EVENT) 
IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 


1 150, 25, ‘To scroll, press MB1.’) 
CALL XSDRAW_IMAGE STRING (DPY, WINDOW, GC, 
1 150, 75, 'To exit, click MB2.’) 
END IF 
IF (EVENT.EVNT_TYPE .EQ. X$C_] BUTTON_PRESS .AND. 
1 EVENT. EVNT " BUTTON. X$L_ BTEV_! BUTTON -EQ. XSC BUTTON) THEN 


BUTTON IS DOWN = 1 
CALL START _SCROLL(DPY, WINDOW, GC, SCROLL PIXELS, 


1 WINDOW W, WINDOW_H, VY) 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON PRESS .AND. 
1 EVENT.EVNT BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN 
CALL SYS$EXIT(%VAL(1)) 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_GRAPHICS EXPOSE) THEN 
0 X = EVENT.EVNT GRAPHICS EXPOSE.X$L_GEEV_X 


Y = EVENT.EVNT GRAPHICS EXPOSE.X$L_GEEV_Y 
WIDTH = EVENT.EVNT_GRAPHICS EXPOSE.X$L_GEEV_WIDTH 
HEIGHT = EVENT.EVNT GRAPHICS EXPOSE.X$L_GEEV_HEIGHT 
DO PY = Y, Y + HEIGHT-1 
DO PX = X, X + WIDTH-1 
IF (MOD(PX + PY + VY, 10) .EQ. 0) THEN 
CALL X$DRAW POINT (DPY, WINDOW, GC, PX, PY) 
END IF 
END DO 
END DO 
IF (BUTTON_IS DOWN .NE. 0) THEN 
CALL START SCROLL(DPY, WINDOW, GC, SCROLL PIXELS, 
i: WINDOW _W, WINDOW_H, VY) 
END IF 
END IF 
IF (EVENT.EVNT TYPE .EQ. X$C_BUTTON RELEASE) THEN 
BUTTON _IS DOWN = 0 
END IF 
IF (EVENT.EVNT_ TYPE .EQ. X$C_NO_EXPOSE) THEN 
IF (BUTTON IS DOWN .NE. 0) THEN 
CALL START SCROLL(DPY, WINDOW, GC, SCROLL PIXELS, 
1 WINDOW _W, WINDOW_H, VY) 
END IF 
END IF 
END DO 


START SCROLL SUBPROGRAM 


@°receec 


SUBROUTINE START SCROLL(DISP, WIN, GCONTEXT, SCR_PIX, WIN_W, 
1 WIN _H, VEC_Y) 


INTEGER*4 DISP, WIN, GCONTEXT, SCR PIX 
INTEGER*4 WIN _W, WIN_H, VEC_Y 





(continued on next page) 
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Example 9-5 (Cont.) Handling Graphics Exposures 


CALL XS$COPY_AREA(DISP, WIN, WIN, GCONTEXT, 0, 
cf SCR_PIX, WIN_W, WIN_H, 0, 0) 
VEC_Y = SCR_PIX + VEC_Y 


END 


@ When a graphics exposure occurs, the client calculates where to draw 


points into the exposed area by referring to members of the expose 
event data structure. 


© The user-defined START_SCROLL routine copies the window contents, 
less one row of pixels, to the top of the window. The result leaves an 
exposed area one pixel high at the bottom of the window. 


© The COPY AREA routine copies new points into the exposed area. 
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9.8 Exposure Events 


Figure 9-13 Window Scrolling 





Graphics Exposure 


To scroll, press MB1. 


To exit, click MB2. 
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9.9 Window State Notification Events 


Xlib reports events related to the state of a window when a client does one 
of the following: 
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Circulates a window, changing the order of the window hierarchy 
Configures a window, changing its position, size, or border 
Creates a window 

Destroys a window 

Changes the size of a parent, causing Xlib to move a child window 


Maps a window 


9.9.1 


Handling Events 
9.9 Window State Notification Events 


¢ Reparents a window 
¢ Unmaps a window 


¢ Changes the visibility of a window 


This section describes handling events that result from these operations. 


Handling Window Circulation 


To receive notification when a client circulates a window, pass either the 
window identifier and the x$m_structure_notify mask or the identifier of 
the parent window and the x$m_substructure_notify mask when using 
a selection method described in Section 9.2. 


Xlib reports to interested clients a change in the hierarchical position 

of a window when a client calls the CIRCULATE SUBWINDOWS, 
CIRCULATE SUBWINDOWS UP, or CIRCULATE SUBWINDOWS DOWN 
routines, 


Xlib uses the circulate event data structure to report circulate events. 
Figure 9-14 illustrates the data structure. 


Figure 9-14 Circulate Event Data Structure 








; 
‘ 
2 
: 
: 
; 

Table 9-19 describes members of the data structure. 

Table 9-19 Circulate Event Data Structure Members 

Member Name Contents 

X$L_CIEV_TYPE Value defined by the constant x$c_circulate_notify. 

X$L_CIEV_SERIAL Number of the last request processed by the 

server. 


{continued on next page) 
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9.9 Window State Notification Events 


Table 9-19 (Cont.) Circulate Event Data Structure Members 


Member Name Contents 

X$L_CIEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_CIEV_DISPLAY Display on which the event occurred. 

X$L_CIEV_EVENT Event window. 

X$L_CIEV_WINDOW Window that has been circulated. 

X$L_CIEV_PLACE Place of the window on the stack after it has been 


circulated. Xlib sets the value of this member 

to either the constant x$c_place_on_top or the 
constant x$c_place_on_bottom. The constant x$c_ 
place_on_top indicates that the window is above 
all siblings. The constant x$c_place_on_bottom 
indicates that the window is below all siblings. 


9.9.2 Handling Changes in Window Configuration 


To receive notification when window size, position, border, or stacking 
order changes, pass either the window identifier and the 
x$m_structure_notify mask or the identifier of the parent window and 
the x$m_substructure_notify mask when using the selection method 
described in Section 9.2. 
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Xlib reports changes in window configuration when the following occur: 


Window size, position, border, and stacking order change when a client 
calls the CONFIGURE WINDOW routine 


Window position in the stacking order changes when a client calls the 
LOWER WINDOW, RAISE WINDOW, or RESTACK WINDOW routine 


Window moves when a client calls the MOVE WINDOW routine 


Window size changes when a client calls the RESIZE WINDOW 
routine 


Window size and location change when a client calls the MOVE 
RESIZE WINDOW routine 


Border width changes when a client calls the SET WINDOW BORDER 
WIDTH routine 


For more information about these routines, see Chapter 3. 


Xlib reports changes to interested clients using the configure event data 
structure. Figure 9-15 illustrates the data structure. 


Handling Events 
9.9 Window State Notification Events 


Figure 9-15 Configure Event Data Structure 









Table 9-20 describes members of the data structure. 
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Table 9-20 Configure Event Data Structure Members 


Member Name Contents 

X$L_CFEV_TYPE Value defined by the constant x$c_cfev_configure_notify. 

X$L_CFEV_SERIAL Number of the last request processed by the server. 

X$L_CFEV_SEND_EVENT Value defined by the constant true if the event came from a SEND 
EVENT request. 

X$A_CFEV_DISPLAY Display on which the event occurred. 

X$L_CFEV_EVENT Event window. 

X$L_CFEV_WINDOW Window that has been reconfigured. 

X$L_CFEV_X The x value of the coordinates that define the upper left corner of the 


window relative to the upper left corner of the parent window. 


X$L_CFEV_Y The y value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 
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Table 9-20 (Cont.) Configure Event Data Structure Members 


Member Name Contents 

X$L_CFEV_WIDTH Width of the window, excluding the border. 

X$L_CFEV_HEIGHT Height of the window, excluding the border. 
X$L_CFEV_BORDER_WIDTH Border width of the reconfigured window. 

X$L_CFEV_ABOVE identifier of the sibling window above which the window is stacked. if this 


member has a value specified by the constant x$c_none, Xlib places the 
window at the bottom of the stack. 


X$L_CFEV_OVERRIDE_REDIRECT lf this member has a value defined by the constant true, the window 
manager ignores requests to reconfigure the window. 


Handling Window Creations 


To receive notification when a client creates a window, pass the identifier 
of the parent window and the x$m_substructure_notify mask when 
using the selection method described in Section 9.2. 


Xlib reports window creations using the create window event data 
structure. Figure 9-16 illustrates the data structure. 


Figure 9-16 Create Window Event Data Structure 
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Table 9-21 describes members of the data structure. 


Table 9-21 Create Window Event Data Structure Members 


Member Name Contents 

X$L_CWEV_TYPE Value defined by the constant x$c_create_notify. 

X$L_CWEV_SERIAL Number of the last request processed by the server. 

X$L_CWEV_SEND_EVENT Value defined by the constant true if the event came from a SEND 
EVENT request. 

X$A_CWEV_DISPLAY Display on which the event occurred. 

X$L_CWEV_EVENT Parent window. 

X$L_CWEV_WINDOW Window that has been created. 

X$L_CWEV_X The x value of the coordinates that define the origin of the window. 

X$L_CWEV_Y The y value of the coordinates that define the origin of the window. 

X$L_CWEV_WIDTH Width of the newly created window, excluding the border. 

X$L_CWEV_HEIGHT Height of the newly created window, excluding the border. 

X$L_CWEV_BORDER_WIDTH Border width of the new window. 


X$L_CWEV_OVERRIDE_REDIRECT If this member has a value defined by the constant true, the window 
manager ignores requests to create the window. 


Handling Window Destructions 


To receive notification when a client destroys a window, pass either the 
window identifier and the x$m_structure_notify mask or the identifier of 
the parent window and the x$m_substructure_notify mask when using 
the selection method described in Section 9.2. 


Xlib reports window destructions using the destroy window event data 
structure. Figure 9-17 illustrates the data structure. 


Figure 9-17 Destroy Window Event Data Structure 
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Table 9-22 describes members of the data structure. 


Table 9-22 Destroy Window Event Data Structure Members 





Member Name Contents 

X$L_DWEV_TYPE Value defined by the x$c_destroy_notify constant. 

X$L_DWEV_SERIAL Number of the last request processed by the 
server. 

X$L_DWEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_DWEV_DISPLAY Display on which the event occurred. 

X$L_DWEV_EVENT Event window. 

X$L_DWEV_WINDOW Window that has been destroyed. 


Handling Changes in Window Position 


To receive notification when a window is moved because a client has 
changed the size of its parent, pass the window identifier and the 
x$m_structure_notify mask or the identifier of the parent window and 
the x$m_substructure_notify mask when using the selection method 
described in Section 9.2. 


Xlib reports window gravity events using the gravity event data structure. 
Figure 9-18 illustrates the data structure. 


Figure 9-18 Gravity Event Data Structure 
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Table 9-23 describes members of the data structure. 


Table 9-23 Gravity Event Data Structure Members 





Member Name Contents 

X$L_GVEV_TYPE Value defined by the x$c_gravity_notify constant. 

X$L_GVEV_SERIAL Number of the last request processed by the 
server. 

X$L_GVEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_GVEV_DISPLAY Display on which the event occurred. 

X$L_GVEV_EVENT Event window. 

X$L_GVEV_WINDOW Child window that has moved. 

X$L_GVEV_X The x value of the coordinates that define the 


upper left corner of the window relative to the 
upper left corner of the parent window. 

X$L_GVEV_Y The y value of the coordinates that define the 
upper left corner of the window relative to the 
upper left corner of the parent window. 


Handling Window Mappings 


To receive notification when a window changes state from unmapped to 
mapped, pass either the window identifier and the x$m_structure_notify 
mask or the identifier of the parent window and the x$m_substructure_ 
notify mask when using the selection method described in Section 9.2. 


Xlib reports window gravity events using the map event data structure. 
Figure 9-19 illustrates the data structure. 


Figure 9-19 Map Window Event Data Structure 
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Table 9-24 describes members of the data structure. 


Table 9-24 Map Event Data Structure Members 


Member Name Contents 

X$L_MPEV_TYPE Value defined by the x$c_map_notify 
constant. 

X$L_MPEV_SERIAL Number of the last request processed by 
the server. 

X$L_MPEV_SEND_EVENT Value defined by the constant true if 
the event came from a SEND EVENT 
request. 

X$A_MPEV_DISPLAY Display on which the event occurred. 

X$L_MPEV_EVENT Event window. 

X$L_MPEV_WINDOW Window that has been mapped. 

X$L_MPEV_OVERRIDE_REDIRECT If the value of this member is defined by 


the constant true, the window manager 
should disregard requests to map the 
window. When true, it overrides a 
substructure redirect on the parent. 


9.9.7 Handling Key, Keyboard, and Pointer Mappings 


All clients receive notification of changes in key, keyboard, and pointer 
mapping. Xlib reports these events when a client has successfully done 
one of the following: 


* Called the SET MODIFIER MAPPING routine to indicate which 
keycodes are modifiers 


* Changed keyboard mapping using the CHANGE KEYBOARD 
MAPPING routine 


¢ Set pointer mapping using the SET POINTER MAPPING routine 


Xlib reports key, keyboard, and pointer mapping events using the mapping 
event data structure. Figure 9—20 illustrates the data structure. 


Figure 9-20 Mapping Event Data Structure 
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Figure 9-20 (Cont.) Mapping Event Data Structure 
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Table 9-25 describes members of the data structure. 
Table 9-25 Mapping Event Data Structure Members 
- Member Name Contents 
X$L_MPPG_TYPE Value defined by the x$c_mapping_notify constant. 
X$L_MPPG_SERIAL Number of the last request processed by the server. 
X$L_MPPG_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 
X$A_MPPG_DISPLAY Display on which the event occurred. 
X$L_MPPG_WINDOW Unused member. 
X$L_MPPG_REQUEST The type of mapping change being reported. Possible values are indicated 
by the following constants: 
x$c_mapping_modifier Specified key codes are used as 
modifiers. 
x$c_mapping_keyboard Keyboard mapping has changed. Sets 
the X$L_MPPG_FIRST_KEYCODE and 
X$L_MPPG_COUNT members. 
x$c_mapping_pointer Pointer button mapping is set. 
X$L_MPPG_FIRST_KEYCODE First number of the range of altered keys, set only if the request member 
has a value specified by the constant x$c_mapping_keyboard. 
X$L_MPPG_COUNT Last number of the range of altered keys, set only if the request member 


has a value specified by the constant x$c_mapping_keyboard. 





Handling Window Reparenting 


To receive notification when the parent of a window changes, pass 
either the window identifier and the x$m_structure_notify mask or 
the identifier of the parent window and the x$m_substructure_notify 
mask when using the selection method described in Section 9.2. 


Xlib reports window reparenting events using the reparent event data 
structure. Figure 9-21 illustrates the data structure. 


9-45 


Handling Events 
9.9 Window State Notification Events 


Figure 9-21 Reparent Event Data Structure 
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Table 9-26 describes members of the data structure. 
Table 9-26 Reparent Event Data Structure Members 
Member Name Contents 
X$L_RPEV_TYPE Value defined by the x$c_reparent_notify constant. 
X$L_RPEV_SERIAL Number of the last request processed by the server. 
X$L_RPEV_SEND_EVENT Value defined by the constant true if the event came from a SEND 
EVENT request. 
X$A_RPEV_DISPLAY Display on which the event occurred. 
X$L_RPEV_EVENT Event window. 
X$L_RPEV_WINDOW Window reparented. 
X$L_RPEV_PARENT New parent of the window. 
X$L_RPEV_X The x value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 
X$L_RPEV_Y The y value of the coordinates that define the upper left corner of the 
window relative to the upper left corner of the parent window. 
X$L_RPEV_OVERRIDE_REDIRECT lf this member has a value defined by the constant true, the window 


manager ignores requests to reparent the window. When true, it 
overrides a substructure redirect on the parent. 
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Handling Window Unmappings 


To receive notification when a window changes from mapped to unmapped, 
pass either the window identifier and the x$m_structure_notify mask 
or the identifier of the parent window and the x$m_substructure_notify 
mask when using the selection method described in Section 9.2. 


Xlib reports window unmapping events using the unmap event data 
structure. Figure 9-22 illustrates the data structure. 


Figure 9-22 Unmap Event Data Structure 






Table 9-27 describes members of the data structure. 









Table 9-27 Unmap Event Data Structure Members 


Member Name Contents 


X$L_UMEV_TYPE Value defined by the x$c_unmap_notify 
constant. 


X$L_UMEV_SERIAL Number of the last request processed by the 
server. 

X$L_UMEV_SEND_EVENT Value defined by the constant true if the 
event came from a SEND EVENT request. 

X$A_UMEV_DISPLAY Display on which the event occurred. 

X$L_UMEV_EVENT Event window. 

X$L_UMEV_WINDOW Window unmapped. 


X$L_UMEV_FROM_CONFIGURE If the value of this member is defined by 
the constant true, the event occurred as a 
result of resizing the parent window when the 
window itself has a window gravity specified 
by the constant x$c_unmap_gravity. 
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Handling Changes in Window Visibility 


All or part of a window is visible if it is mapped to a screen, if all of its 
ancestors are mapped, and if it is at least partially visible on the screen. 
To receive notification when the visibility of a window changes, pass the 
window identifier and the x$m_structure_notify mask when using the 
selection method described in Section 9.2. 


Xlib reports changes in visibility to interested clients using the visibility 
event data structure. Figure 9-23 illustrates the data structure. 


Figure 9-23 Visibility Event Data Structure 
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Table 9-28 describes members of the data structure. 


Table 9-28 Visibility Event Data Structure Members 





Member Name Contents 

X$L_VSEV_TYPE Value defined by the x$c_visibility_notify constant. 

X$L_VSEV_SERIAL Number of the last request processed by the server. 

X$L_VSEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 

X$A_VSEV_DISPLAY Display on which the event occurred. 

X$L_VSEV_WINDOW Window whose visibility changed. 

X$L_VSEV_STATE If set to the value defined by the x$c_visibility_unobscured constant, the 


window has changed from being partially and fully obscured to being fully 
visible. If set to the value defined by the x$c_visibility_part_obscured, the 
window has changed from being fully obscured or fully visible to partially 
obscured. If set to the value defined by the x$c_visibility_fully_obscured 
constant, the window has changed from being fully visible or partially obscured 
to not visible. 
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9.10 Color Map State Events 


Xlib reports a color map event when the window manager installs, 
changes, or removes the color map. 


To receive notification of color map events, pass the window identifier 
and the x$m_colormap_change mask when using the selection method 
described in Section 9.2. 


Xlib reports color map events to interested clients when the following 
occur: 


¢ Acclient sets the color map member of the set window attributes data 
structure by calling CHANGE WINDOW ATTRIBUTES. See Chapter 3 
for more information on the data structure and routine. 


¢ Aclient calls the FREE COLORMAP routine. See Section 5.5 for more 
information about FREE COLORMAP. 


e¢ The window manager installs or removes a color map in response 
to either a client call of the INSTALL COLORMAP or UNINSTALL 
COLORMAP routine. 


Xlib reports color map events using the color map event data structure. 
Figure 9-24 illustrates the data structure. 


Figure 9-24 Color Map Event Data Structure 
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Table 9-29 describes members of the data structure. 


Table 9-29 Color Map Event Data Structure Members 


Member Name 


X$L_CMEV_TYPE 
X$L_CMEV_SERIAL 
X$L_CMEV_SEND_EVENT 


X$A_CMEV_DISPLAY 


X$L_CMEV_WINDOW 


X$L_CMEV_COLORMAP 


X$L_CMEV_NEW 


X$L_CMEV_STATE 


Conients 


Value defined by the x$c_colormap_notify constant. 
Number of the last request processed by the server. 


Value defined by the constant true if the event came from a SEND EVENT 
request. 


Display on which the event occurred. 
Window whose associated color map has changed. 


lf the window manager changes the color map in response to a call to CHANGE 
WINDOW ATTRIBUTES, INSTALL COLORMAP, or UNINSTALL COLORMAP, 
this member has a value specified by the constant x$c_colormap. If the window 
manager changes the color map in response to a call to FREE COLORMAP, 
this member has a value specified by the constant x$c_none. 


Value defined by the constant true if the window manager has changed the 
color map or the value defined by the constant false if the window manager has 
installed or removed the color map. 


Value defined by the constant x$c_colormap_installed if the color map is 
installed. The value defined by the constant x$c_colormap_uninstalled if the 
color map is not installed. 





9.11 Client Communication Events 


Xlib reports an event when one of the following occurs: 


c J 


One client notifies another client that an event has happened. 
A client changes, deletes, rotates, or gets a property. 
A client loses ownership of a window. 


A client requests ownership of a window. 


This section describes how to handle communication between clients. 


9.11.1. Handling Event Notification from Other Clients 


Clients can notify each other of events by calling the SEND EVENT 
routine. 


Xlib sends notification between clients using the client message event data 
structure. Figure 9—25 illustrates the data structure. 
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Figure 9-25 Client Message Event Data Structure 
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Table 9-30 describes members of the data structure. 


Table 9-30 Client Message Event Data Structure Members 


Member Name Contents 

X$L_CLNT_TYPE Value defined by the x$c_client_message constant. 

X$L_CLNT_SERIAL. Number of the last request processed by the server. 

X$L_CLNT_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 

X$A_CLNT_DISPLAY Display on which the event occurred. 

X$L_CLNT_WINDOW Window to which the message is sent. 

X$L_CLNT_MESSAGE_TYPE Indicates how the message data is to be interpreted by the receiving client. 
For more information about atoms, see Chapter 3. 

X$L_CLNT_FORMAT Indicates whether the data is in units of 8, 16, or 32 bits. 

X$B_CLNT_B Data of 20 8-bit values. 


9.11.2 Handling Changes in Properties 


As Chapter 3 notes, a property associates a constant with data of a 
particular type. Xlib reports a property event when a client does one of 
the following: 
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e¢ Changes a property 

¢ Rotates a window property 

¢ Gets a property 

¢ Deletes a property 

To receive information about property changes, pass the window identifier 


and the x$m_property_change mask when using the selection method 
described in Section 9.2. 


Xlib reports changes in properties to interested clients using the property 
event data structure. Figure 9—26 illustrates the data structure. 


Figure 9-26 Property Event Data Structure 
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Table 9-31 Property Event Data Structure Members 








Member Name Contents 

X$L_PPEV_TYPE Value defined by the x$c_property_notify constant. 

X$L_PPEV_SERIAL Number of the last request processed by the server. 

X$L_PPEV_SEND_EVENT Value defined by the constant true if the event came from a SEND EVENT 
request. 

X$A_PPEV_DISPLAY Display on which the event occurred. 





X$L_PPEV_WINDOW Window whose property was changed. 
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Table 9-31 (Cont.) Property Event Data Structure Members 








Member Name Contents 

X$L_PPEV_ATOM Identifies the property that was changed. For more information about properties 
and atoms, see Chapter 3. 

X$L_PPEV_TIME Server time that the property changed. 

X$L_PPEV_STATE Value specified by the constant x$c_property_new_value if a client changes 


a property by calling either the CHANGE PROPERTY or the ROTATE 
PROPERTY routine. The same result occurs if the client replaces all or 

part of a property with identical data using CHANGE PROPERTY or ROTATE 
PROPERTY. 

The value specified by the constant x$c_property_delete if a client deletes a 
property by calling either the DELETE PROPERTY or the GET PROPERTY 
routine. For more information about properties, see Chapter 3. 


Handling Changes in Selection Ownership 


Clients receive notification automatically when they are losing ownership 
of a window. Xlib reports the event when a client takes ownership of a 
window by calling the SET SELECTION OWNER routine. 


To report the event, Xlib uses the selection clear event data structure. 
Figure 9—27 illustrates the data structure. 


Figure 9-27 Selection Clear Event Data Structure 









Table 9-32 describes members of the data structure. 
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Table 9-32 Selection Clear Event Data Structure Members 





Member Name Contents 

X$L_SCEV_TYPE Value defined by the x$c_selection_clear constant. 

X$L_SCEV_SERIAL Number of the last request processed by the 
server. 

X$L_SCEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_SCEV_DISPLAY Display on which the event occurred. 

X$L_SCEV_WINDOW Window losing ownership of the selection. 

X$L_SCEV_SELECTION Selection atom. For more information about atoms 
and selection, see Chapter 3. 

X$L_SCEV_TIME Last time change recorded for the selection. 


9.11.4 Handling Requests to Convert a Selection 


The server issues a selection request event to the owner of a selection 
when. a client calls the CONVERT SELECTION routine. For information 
about the CONVERT SELECTION routine, see Section 3.5.2. 


To report the event, Xlib uses the selection request event data structure. 
Figure 9—28 illustrates the data structure. 


Figure 9-28 Selection Request Event Data Structure 
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Table 9~33 describes members of the selection request event data 
structure. 
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Table 9-33 Selection Request Event Data Structure Members 


Member Name Contents 

X$L_SREV_TYPE Value defined by the x$c_selection_request 
constant. 

X$L_SREV_SERIAL Number of the last request processed by the 
server. 

X$L_SREV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 

X$A_SREV_DISPLAY Display on which the event occurred. 

X$L_SREV_OWNER Window that owns the selection. 

X$L_SREV_REQUESTOR Window that requests the selection. 

X$L_SREV_SELECTION Selection atom. For more information about atoms 
and selection, see Chapter 3. 

X$L_SREV_TARGET Data type that selection is converted to before 
being returned. 

X$L_SREV_PROPERTY Atom that specifies a property or the constant 
x$c_none. 

X$L_SREV_TIME Timestamp, expressed in milliseconds, or the 


constant x$c_current_time from the convert 
selection request. 


9.11.5 Handling Requests to Notify of a Selection 


The server issues a selection notify event to the requestor of a selection 
after the selection has been converted and stored as a property. 


For information about the CONVERT SELECTION routine, see 
Section 3.5.2. To report the event, Xlib uses the selection event data 
structure. Figure 9-29 illustrates the data structure. 


Figure 9-29 Selection Event Data Structure 
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Figure 9-29 (Cont.) Selection Event Data Structure 
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Table 9-34 describes members of the selection event data structure. 
Table 9-34 Selection Event Data Structure Members 
Member Name Contents 
X$L_SLEV_TYPE Value defined by the x$c_selection_notify constant. 
X$L_SLEV_SERIAL Number of the last request processed by the 
server. 
X$L_SLEV_SEND_EVENT Value defined by the constant true if the event 
came from a SEND EVENT request. 
X$A_SLEV_DISPLAY Display on which the event occurred. 
X$L_SLEV_REQUESTOR Window that has requested the selection. 
X$L_SLEV_SELECTION Selection atom. For more information about atoms 
and selection, see Chapter 3. 
X$L_SLEV_TARGET Data type to which selection is converted. 
X$L_SLEV_PROPERTY Atom that specifies a property or the constant 
x$c_none. 
X$L_SLEV_TIME Timestamp, expressed in milliseconds, or the 


constant x$c_current_time from the convert 
selection request. 


9.12 Event Queue Management 


Xlib maintains an input queue known as the event queue. When an 
event occurs, the server sends the event to Xlib, which places it at the end 
of an event queue. By using routines described in this section, the client 
can check, remove, and process the events on the queue. As the client 
removes an event, remaining events move up the event queue. 


Certain routines may block or prevent other routine calls from accessing 
the event queue. If the blocking routine does not find an event that the 
client is interested in, Xlib flushes the output buffer and waits until an 
event is received from the server. 


This section describes how the event queue is managed, including the 
following topics: 


* Checking events on the queue 
* Returning events in order and removing them from the queue 


¢ Returning events without removing them from the queue 
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¢ Obtaining events that match the event mask or the arbitrary functions 
that the client provides 


¢ Putting events back onto the event queue 


¢ Sending events to other clients 


9.12.1 Checking the Contents of the Event Queue 


To check the event queue without preventing other routines from accessing 
the queue, use the EVENTS QUEUED routine. Clients can check events 
already queued by calling the EVENTS QUEUED routine and specifying 
one of the following constants: 


x$c_queued_already Returns the number of events already in the event 
queue and never performs a system call. 

x$c_queued_after_flush Returns the number of events in the event queue if 
the value is a nonzero. If there are no events in the 
queue, this routine flushes the output buffer, attempts 
to read more events out of the client connection, and 
returns the number read. 

x$c_queued_after_reading Returns the number of events already in the event 
queue if the value is a nonzero. If there are no events 
in the queue, this routine attempts to read more 
events out of the client connection without flushing the 
output buffer and returns the number read. 


To return the number of events in the event queue, use the PENDING 
routine. If there are no events in the queue, PENDING flushes the output 
buffer, attempts to read more events out of the client connection, and 
returns the number read. The PENDING routine is identical to EVENTS 
QUEUED with constant x$e_queued_after_flush specified. 


9.12.2 Returning the Next Event on the Queue 


To return the first event on the event queue and copy it into the specified 
event data structure, use the NEXT EVENT and PEEK EVENT routines. 
NEXT EVENT returns the first event, copies it into an EVENT structure, 
and removes it from the queue. PEEK EVENT returns the first event, 
copies it into an event data structure, but does not remove it from the 
queue. In both cases, if the event queue is empty, the routine flushes the 
output buffer and blocks until an event is received. 


9.12.3 Selecting Events That Match User-Defined Routines 


Xlib enables the client to check all the events on the queue for a specific 
type of event by specifying a client-defined routine known as a predicate 
procedure. The predicate procedure determines if the event on the queue 
is one that the client is interested in. 


The client calls the predicate procedure from inside the event routine. 
The predicate procedure should determine only if the event is useful and 
must not call Xlib routines. The predicate procedure is called once for each 
event in the queue until it finds a match. 


9-57 


9.12.4 


Handling Events 
9.12 Event Queue Management 


Table 9~35 lists routines that use a predicate procedure and indicates 
whether or not the routine blocks. 


Table 9-35 Selecting Events Using a Predicate Procedure 


Routine Description Blocking/No Blocking 





IF EVENT Checks the event queue for the specified event. Blocking 
If the event matches, removes the event from the 
queue. This routine is also called each time an 
event is added to the queue. 


CHECK IF EVENT Checks the event queue for the specified event. No blocking 
If the event matches, removes the event from the 
queue. If the predicate procedure does not find a 
match, it flushes the output buffer. 


PEEK IF EVENT Checks the event queue for the specified event but Blocking 
does not remove it from the queue. This routine 
is also called each time an event is added to the 
queue. 





Selecting Events Using an Event Mask 


Xlib enables a client to process events out of order by specifying a window 
identifier and one of the event masks listed in Table 9-3 when calling 
routines listed in Table 9-36. 


For example, the following specifies keyboard events on window WINDOW 
by using the event mask name constant x$c_keymap_state_mask. 


CALL XSWINDOW_EVENT(DPY, WINDOW, 
1 X$C_KEYMAP_ STATE, EVENT) 


Table 9-36 lists routines that use event or window masks and indicates 
whether the routine blocks. 


Table 9-36 Routines to Select Events Using a Mask 


Routine Description Blocking/No Blocking 
WINDOW EVENT Searches the event queue and removes the next Blocking 

event that matches both the specified window and 

event mask 
CHECK WINDOW EVENT Searches the event queue, then the events No blocking 


available on the server connection, and removes 
the first event that matches the specified event and 
window mask 


MASK EVENT Searches the event queue and removes the next Blocking 
event that matches the event mask 
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Table 9-36 (Cont.) Routines to Select Events Using a Mask 


Routine 


CHECK MASK EVENT 


CHECK TYPED EVENT 


CHECK TYPED WINDOW 
EVENT 


Description Blocking/No Blocking 


Searches the event queue, then the events No blocking 
available on the server connection, and removes 
the next event that matches an event mask 


Returns the next event in the queue that matches No blocking 
an event type 


Searches the event queue, then the events No blocking 
available on the server connection, and removes 

the next event that matches the specified type and 

window 


Putting an Event Back on Top of the Queue 


To push an event back onto the top of the event queue, use the PUT BACK 
EVENT routine. PUT BACK EVENT is useful when a client returns an 
event from the queue and decides to use it later. There is no limit to how 
many times in succession PUT BACK EVENT can be called. 


Sending Events to Other Clients 


To send an event to a client, use the SEND EVENT routine. For example, 
owners of a selection should use this routine to send a SELECTION 
NOTIFY event to a requestor when a selection has been converted and 
stored as a property. 





Error Handling 


Xlib has two default error handlers. One manages fatal errors, such as 
when the connection to a display is severed due to a system failure. The 
other handles error events from the server. The default error handlers 
print an explanatory message and text and then exit. 


Each of these error handlers can be replaced by client error handling 
routines. If a client-supplied routine is passed a null pointer, Xlib 
reinvokes the default error handler. 


This section describes the Xlib event error handling resources including 
enabling synchronous operation, handling server errors, and handling 
input/output (I/O) errors. 


Enabling Synchronous Operation 


When debugging programs it is convenient to require Xlib to behave 
synchronously so that errors are reported at the time they occur. 


To enable synchronous operation, use the SYNCHRONIZE routine. The 
client passes the display argument and the onoff argument. The onoff 
argument passes either a value of zero (disabling synchronization) or a 
nonzero value (enabling synchronization). 
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9.13.2 Using the Default Error Handlers 


To handle error events when an error event is received, use the SET 
ERROR HANDLER routine. 


Xlib provides an error event data structure that passes information to the 
SET ERROR HANDLER routine. 


Figure 9-30 illustrates the error event data structure. 


Figure 9-30 Error Event Data Structure 












x$b_erev_minor_code x$b_erev_request_code x$b_erev_error_code 


Table 9~37 describes the members of the data structure. 





Table 9-37 Error Event Data Structure Members 


Member Name Description 


X$L_EREV_TYPE Type of error event being reported 
X$A_EREV_DISPLAY Display on which the error event occurred 


X$L_EREV_SERIAL Number of requests starting at one sent over the 
network connection since it was opened 


X$B_EREV_ERROR_CODE identifying error code of the failing routine 


X$B_EREV_REQUEST_CODE Protocol representation of the name of the 
procedure that failed and defined in X11/X.h 


X$B_EREV_MINOR_CODE Minor opcode of failed request 
X$L_EREV_RESOURCE_ID Resource ID 


The routines described in this section return Xlib error codes. Table 9-38 
lists the codes and describes the errors. 
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Table 9-38 Event Error Codes 


Error Code 


X$C_BAD_ACCESS 


X$C_BAD_ALLOC 
X$C_BAD_ATOM 
X$C_BAD_COLOR 
X$C_BAD_CURSOR 
X$C_BAD_DRAWABLE 


X$C_BAD_FONT 
X$C_BAD_GC 


X$C_BAD_ID_CHOICE 


X$C_BAD_ 
IMPLEMENTATION 


X$C_BAD_LENGTH 


X$C_BAD_MATCH 


X$C_BAD_NAME 
X$C_BAD_PIXMAP 


Description 


Possible causes are: 


« An attempt to grab a key/button combination that has already been grabbed by 
another client. 

* An attempt to free a color map entry that was not allocated by the client. 

« An attempt to store into a read-only, or unallocated, color map entry. 

+ An attempt to modify the access control list from other than the local host. 


* An attempt to select an event type that only one client can select at a time when 
another client has already selected it. 


The server did not allocate the requested resource for any cause. 

The value specified in an atom argument does not name a defined atom. 

A value specified for a color map argument does not name a defined color map. 

A value specified for a cursor argument does not name a defined cursor. 

A value specified for a drawable argument does not name a defined window or 
pixmap. 

A value specified for a font argument does not name a defined font (or, in some 
cases, graphics context). 

A value specified for a graphics context argument does not name a defined graphics 
context. 


The value specified for a resource identifier is either not included in the range 
assigned to the client, or is already in use. Under normal circumstances this cannot 
occur and should be considered a server or Xlib error. 


The server does not implement some aspect of the request. This error is most likely 
caused by a server extension; a server that generates this error for a core protocol 
request is deficient. As such, this error is not listed for any particular request. Clients 
should be prepared to receive this type of error and either handle or discard it. 


The length of a request is shorter or longer than required to minimally contain the 
arguments. This error usually indicates an internal Xlib or server error. The length of 
a request exceeds the maximum length accepted by the server. 


Possible causes are: 

* Ina graphics request, the root and depth of the graphics context does not match 
that of the drawable. 

¢ — An input-only window is used as a drawable. 


* One argument or pair of arguments has the correct type and range but fails to 
match in some other way required by the request. 


* — An input only window lacks this attribute. 


The font or color specified does not exist. 
A value specified for a pixmap argument does not name a defined pixmap. 
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Table 9-38 (Cont.) Event Error Codes 


Error Code 


X$C_BAD_REQUEST 


X$C_BAD_VALUE 


X$C_BAD_WINDOW 


Description 


The major or minor opcode specified does not indicate a valid request. This is usually 
an Xlib or server error. 

Some numeric values fall outside the range of values accepted by the request. 
Unless a specific range is specified for an argument, the full range defined by the 
argument’s type is accepted. Any argument defined as a set of alternatives can 
generate this error. 


A value specified for a window argument does not name a defined window. 


Note that Bad Atom, Bad Color, Bad Cursor, Bad Drawable, Bad Font, 
Bad Pixmap, and Bad Window errors are also used when the argument 
type is extended by a set of fixed alternatives. 


To obtain a text description of the specified error code, use the GET 
ERROR TEXT routine. This routine copies a null terminated string 
describing the specified error code into the specified buffer. The client 
should use this routine to obtain an error description because extensions 
to Xlib may define their own error codes and error strings. 


To obtain error messages from the error database, use the GET ERROR 
DATABASE TEXT routine. This routine returns a message (or the default 
message) from the error message database. The GET ERROR DATABASE 
TEXT uses the resource manager to look up a string and returns it in the 
buffer argument. Xlib uses this function internally to look up its error 
messages. 


To report an error when the requested display does not exist, use the 
DISPLAY NAME routine. This routine returns the name of the display 
that the client is currently using. The DISPLAY NAME routine passes 
the argument string. If null string is specified, DISPLAY NAME looks in 
the environment and returns the display name requested. This makes it 
easier to report precisely which display the client attempted to open when 
the initial connection attempt failed. 


To handle fatal I/O errors, use the SET IO ERROR HANDLER routine. 
Xlib calls the supplied error handler if any system call error occurs (for 
example, the connection to the server is lost). In this case, the called 
routine should not return. If the I/O handler does return, the client exits. 


A 


Compiling Fonts 


VMS DECwindows includes a font compiler that enables programmers 
to convert an ASCII bitmap distribution format (BDF) into binary server 
natural form (SNF). The server uses an SNF file to display a font. In 
addition to converting the BDF file to binary form, the compiler provides 
statistical information about the font and the compilation process. 


To invoke the font compiler, use the following format: 


FONT filespec [ 
/[NOJOUTPUT[=filename] 
/[NO]JMINBBOX 
/[NO]JREPORT 


] 


The filename parameter specifies the BDF file to be converted. A 
file name is required. The default value of the optional file type is 
DECWSBDF. 


The /OUTPUT qualifier specifies the file name and type of the resulting 
SNF file. The default output file name is the file name of the BDF file 
being converted. The default output SNF file type is DECW$FONT. 


Compiler output consists of a header file that contains font information, 
character metrics, and the image of each character in the font. Font 
information in the header file is essentially the same as information stored 
in the font struct data structure. For a description of the data structure, 
see Section 8.1. 


The /MINBBOX qualifier specifies that the compiler produce the minimum 
bounding box for each character in the font and adjust values for the left 
bearing, right bearing, ascent, and descent of each character accordingly. 
Character width is not affected. Specifying the /MINBBOX qualifier 

is equivalent to converting a fixed font to a monospaced font. For a 
description of character metrics and fonts, see Section 8.1. 


Using the /MINBBOX qualifier has two advantages. Because the font 
compiler produces minimum instead of fixed bounding boxes, the resulting 
SNF file is significantly smaller than the comparable fixed font SNF file. 
Consequently, both disk requirements for storing the font and server 
memory requirements when a client loads the font are reduced. Also, 
because the resulting font comprises minimum inkable characters, server 
performance when writing text is increased as much as 20 percent. 


The /REPORT qualifier directs the compiler to report information about 
the font and the conversion process, including BDF information, font 
properties, compiler generation information, and metrics. The /REPORT 
qualifier also causes the compiler to illustrate each glyph in the font. 


Routines Requiring Protocol Requests 


Table B—1 lists Xlib routines requiring protocol requests. The table 
provides the protocol request and a short description for each Xlib function. 


Table B-1 Routines Requiring Protocol Requests 





Xlib Function 


ALLOC COLOR 


ALLOC COLOR CELLS 


ALLOC COLOR PLANES 


ALLOC NAMED COLOR 


CHANGE GC 


CHANGE PROPERTY 


CHANGE WINDOW ATTRIBUTES 


CIRCULATE SUBWINDOWS 


CIRCULATE SUBWINDOWS DOWN 


CIRCULATE SUBWINDOWS UP 


CLEAR AREA 


CLEAR WINDOW 


CONFIGURE WINDOW 


CONVERT SELECTION 
COPY AREA 


Protocol Request 


ALLOC COLOR 
ALLOC COLOR CELLS 
ALLOC COLOR PLANES 


ALLOC NAME COLOR 


CHANGE GC 
CHANGE PROPERTY 
CHANGE WINDOW 
ATTRIBUTES 
CIRCULATE WINDOW 
CIRCULATE WINDOW 
CIRCULATE WINDOW 
CLEAR AREA 

CLEAR AREA 


CONFIGURE WINDOW 


CONVERT SELECTION 
COPY AREA 


Description 


Allocates a read-only color cell 


Allocates read/write color cells and 
color plane combinations for a 
PseudoColor model 


Allocates read/write color resources for 
DirectColor visual types 


Allocates a read-only color ceil by 
name and returns the closest color 
supported by the hardware 


Changes the components in the 
specified graphics context 


Changes the property of a specified 
window 


Changes one or more window 
attributes 


Circulates a subwindow up or down 


Lowers the highest mapped child of 
a window that partially or completely 
occludes another child 


Raises the lowest mapped child of an 
occluded window 


Clears a specified rectangular area of 
the specified window 


Clears the entire area in the specified 
window 


Configures a window’s size, location, 
stacking, or border 


Requests conversion of a selection 


Copies an area of the specified 
drawable between drawables of the 
same root and depth 
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Xlib Function 


COPY COLORMAP AND FREE 


COPY GC 


COPY PLANE 


CREATE COLORMAP 
CREATE FONT CURSOR 
CREATE GC 


CREATE GLYPH CURSOR 


CREATE PIXMAP 


CREATE PIXMAP CURSOR 


CREATE SIMPLE WINDOW 


CREATE WINDOW 


DEFINE CURSOR 


DELETE PROPERTY 


DESTROY SUBWINDOWS 


DESTROY WINDOW 


DRAW ARC 


DRAW ARCS 


DRAW IMAGE STRING 


DRAW IMAGE STRING 16 


DRAW LINE 


DRAW LINES 
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COPY COLORMAP AND FREE 


COPY GC 


COPY PLANE 


CREATE COLORMAP 
CREATE GLYPH CURSOR 
CREATE GC 


CREATE GLYPH CURSOR 
CREATE PIXMAP 
CREATE CURSOR 
CREATE WINDOW 
CREATE WINDOW 
CHANGE WINDOW 
ATTRIBUTES 

DELETE PROPERTY 
DESTROY SUBWINDOWS 
DESTROY WINDOW 
POLY ARC 

POLY ARC 

IMAGE TEXT 8 

IMAGE TEXT 16 


POLY SEGMENT 


POLY LINE 


Description 


Creates a new color map when 
allocating out of a previously shared 
color map has failed due to resource 
exhaustion 


Copies components from a source 
graphics context to a destination 
graphics context 


Copies a single bit-plane of the 
specified drawabie 


Creates a color map for a screen 
Creates a cursor from a standard font 


Creates a new graphics context that is 
usable with the specified drawable 


Creates a cursor from font glyphs 
Creates a pixmap of a specified size 
Creates a cursor from two bitmaps 


Creates an unmapped input-output 
subwindow of the specified parent 
window 


Creates an unmapped subwindow for a 
specified parent window 


Defines which cursor will be used in a 
window 


Deletes a property for the specified 
window 


Destroys all subwindows of a specified 
window 


Destroys a window and all of its 
subwindows 


Draws a single arc in the specified 
drawable 


Draws multiple arcs in the specified 
drawable 


Draws 8-bit image text characters in 
the specified drawable 


Draws 2-byte image text characters in 
the specified drawable 


Draws a single line between two points 
in the specified drawable 


Draws multiple lines in the specified 
drawable 
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DRAW POINT 


DRAW POINTS 


DRAW RECTANGLE 


DRAW RECTANGLES 


DRAW SEGMENTS 


DRAW STRING 


DRAW STRING 16 


DRAW TEXT 


DRAW TEXT 16 


FETCH BYTES 
FETCH NAME 
FILL ARC 


FILL ARCS 


FILL. POLYGON 


FILL RECTANGLE 


FILL RECTANGLES 


FREE COLORMAP 


FREE COLORS 


FREE CURSOR 
FREE FONT 


FREE GC 
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POLY POINT 
POLY POINT 
POLY RECTANGLE 
POLY RECTANGLE 


POLY SEGMENT 


POLY TEXT 8 
POLY TEXT 16 
POLY TEXT 8 
POLY TEXT 16 


GET PROPERTY 
GET PROPERTY 
POLY FILL ARC 


POLY FILL ARC 

FILL POLY 

POLY FILL RECTANGLE 
POLY FILL RECTANGLE 
FREE COLOR MAP 
FREE COLOR 


FREE CURSOR 
CLOSE FONT 


FREE GC 


Description 


Draws a single point in the specified 
drawable 


Draws multiple points in the specified 
drawable 


Draws the outline of a single rectangle 
in the specified drawable 


Draws the outline of multiple rectangles 
in the specified drawable 


Draws multiple but not necessarily 
connected lines in the specified 
drawable 


Draws 8-bit characters in the specified 
drawable 


Draws 2-byte characters in the 
specified drawable 


Draws 8-bit characters in the specified 
drawable 


Draws 2-byte characters in the 
specified drawable 


Returns data from cut buffer 0 
Gets the name of a window 


Fills a single arc in the specified 
drawable 


Fills multiple arcs in the specified 
drawable 


Fills a polygon area in the specified 
drawable 


Fills a single rectangular area in the 
specified drawable 


Fills multiple rectangular areas in the 
specified drawable 


Deletes the association between the 
color map resource ID and the color 
map 


Frees color map cells 
Frees (destroys) the specified cursor 


Unloads the font and frees the storage 
used by the font data structure that 
was allocated by QUERY FONT and 
LOAD QUERY FONT 


Frees the specified graphics context 
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Xlib Function 


FREE PIXMAP 


GET ATOM NAME 


GET FONT PATH 
GET GEOMETRY 


GET ICON SIZES 


GET IMAGE 


GET MOTION EVENTS 


GET NORMAL HINTS 


GET SELECTION OWNER 
GET SIZE HINTS 


GET WM HINTS 


GET WINDOW ATTRIBUTES 


GET WINDOW PROPERTY 


GET ZOOM HINTS 


INIT EXTENSION 


INTERN ATOM 
LIST EXTENSIONS 


LIST FONTS 


LIST FONTS WITH INFO 


LIST PROPERTIES 


LOAD FONT 


Protocol Request 


FREE PIXMAP 
GET ATOM NAME 


GET FONT PATH 
GET GEOMETRY 


GET PROPERTY 

GET IMAGE 

GET MOTION EVENTS 
GET PROPERTY 


GET SELECTION OWNER 
GET PROPERTY 


GET PROPERTY 
GET WINDOW ATTRIBUTES 
GET GEOMETRY 
GET PROPERTY 
GET PROPERTY 


QUERY EXTENSION 


INTERN ATOM 
LIST EXTENSIONS 


LIST FONTS 
LIST FONTS WITH INFO 
LIST PROPERTIES 


OPEN FONT 


Description 


Frees all storage associated with a 
specified pixmap 

Returns a name for the specified atom 
identifier 

Gets the current font search path 


Obtains the current geometry of the 
specified drawable 


Returns the value of the icon sizes 
atom 


Returns the contents of a rectangle in 
the specified drawable on the display 


Gets the motion history for a specified 
window and time 

Returns the size hints for a window in 
its normal state 

Returns the selection owner 


Reads the value of any property of 
type WM_SIZE_HINTS 


Reads the value of the window 
manager hints atom 


Obtains the current attributes or 
geometry of a specified window 


Obtains the atom type and property 
format of a specified window 


Reads the value of the zoom hints 
atom 


Allocates storage for maintaining 
the information about the extension 
on the connection, chains this onto 
the extension list, and returns the 
information the stub implementor 
needs to access the extension 


Returns an atom for a specified name 


Returns a list of all extensions 
supported by the server 


Returns a list of the available font 
names 


Obtains the names and information 
about loaded fonts 


Obtains the specified window’s 
property list 
Loads the specified font 
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Xlib Function 


Protocol Request 


Description 





LOAD QUERY FONT 


LOOKUP COLOR 
LOWER WINDOW 


MAP RAISED 


MAP SUBWINDOWS 


MAP WINDOW 
MOVE RESIZE WINDOW 
MOVE WINDOW 


NO OP 


OPEN DISPLAY 


PARSE COLOR 
PUT IMAGE 


QUERY BEST CURSOR 
QUERY BEST SIZE 


QUERY BEST STIPPLE 
QUERY BEST TILE 
QUERY COLOR 


QUERY COLORS 


QUERY EXTENSION 


QUERY POINTER 


QUERY TEXT EXTENTS 


OPEN FONT 
QUERY FONT 


LOOKUP COLOR 
CONFIGURE WINDOW 


CONFIGURE WINDOW 
MAP WINDOW 
MAP SUBWINDOWS 


MAP WINDOW 
CONFIGURE WINDOW 
CONFIGURE WINDOW 


NO OPERATION 


CREATE GC 


LOOKUP COLOR 
PUT IMAGE 


QUERY BEST SIZE 
QUERY BEST SIZE 


QUERY BEST SIZE 
QUERY BEST SIZE 
QUERY COLORS 


QUERY COLORS 


QUERY EXTENSION 


QUERY POINTER 


QUERY TEXT EXTENTS 


Performs a LOAD FONT and QUERY 
FONT in a single operation 


Looks up the name of a color 


Lowers a window so that it does not 
obscure any sibling window 


Maps and raises a window 


Maps all subwindows for a specified 
window 


Maps the specified window 

Changes size and location of a window 
Moves a window without changing its 
size 

Sends a NoOperation request to the 
server 


Opens a connection to the server 
controlling the specified display 


Parses color values 


Combines an image in memory with a 
rectangle of a drawable on the display 


Determines useful cursor sizes 


Obiains the best size of a tile, stipple, 
or cursor 


Obtains the best stipple shape 
Obtains the fill tile shape 


Queries the RGB values of a single 
specified pixel value 


Queries the RGB values of an array 
of pixels stored in the color data 
structures 


Determines if the named extension 
is present and, if so, returns major 
opcode for the extension 


Obtains the root window the pointer 
is currently on and the pointer 
coordinates relative to the root’s 
origin 

Queries the server for the bounding 
box of a 1-byte character string 
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QUERY TEXT EXTENTS 16 


QUERY TREE 


RAISE WINDOW 


RECOLOR CURSOR 


RESIZE WINDOW 


RESTACK WINDOWS 


ROTATE BUFFERS 
ROTATE WINDOW PROPERTIES 


SELECT INPUT 


SEND EVENT 


SET ARC MODE 


SET BACKGROUND 


SET CLIP MASK 


SET CLIP ORIGIN 


SET CLIP RECTANGLES 


SET COMMAND 
SET DASHES 


SET FILL RULE 


SET FILL STYLE 


Protocol Request 


QUERY TEXT EXTENTS 


QUERY TREE 


CONFIGURE WINDOW 
RECOLOR CURSOR 

CONFIGURE WINDOW 
CONFIGURE WINDOW 


ROTATE PROPERTIES 
ROTATE PROPERTIES 


CHANGE WINDOW 
ATTRIBUTES 


SEND EVENT 
CHANGE GC 


CHANGE GC 


CHANGE GC 


CHANGE GC 


SET CLIP RECTANGLES 


CHANGE PROPERTY 
SET DASHES 


CHANGE GC 


CHANGE GC 


Description 


Queries the server for the bounding 
box of a 2-byte character string in the 
specified font 


Obtains a list of children, the parent, 
and number of children for a specified 
window 


Raises a window so that no sibling 
window obscures it 


Changes the color of the specified 
cursor 


Changes a window’s size without 
changing the upper left coordinate 


Restacks a set of windows from top to 
bottom 


Rotates the cut buffers 


Rotates properties in the properties 
array 


Requests server to report events 
associated with the event masks 
passed to the event_mask argument 


Sends an event to a specified window 


Sets the arc mode of the specified 
graphics context 


Sets the background of the specified 
graphics context 


Sets the clip_mask of the specified 
graphics context to the specified 
pixmap 

Sets the clip origin of the specified 
graphics context 


Sets the clip mask of the specified 
context to the specified list of 
rectangles 


Sets the value of the command atom 
Sets the dash_offset and dash_list 


for dashed line styles of the specified 
graphics context 


Sets the fill rule of the specified 
graphics context 


Sets the fill style of the specified 
graphics context 
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SET FONT 


SET FONT PATH 
SET FOREGROUND 


SET FUNCTION 


SET GRAPHICS EXPOSURES 


SET ICON SIZES 
SET LINE ATTRIBUTES 


SET NORMAL HINTS 


SET PLANE MASK 


SET SELECTION OWNER 
SET SIZE HINTS 


SET STANDARD PROPERTIES 


SET STATE 


SET STIPPLE 

SET SUBWINDOW MODE 
SET TILE 

SET TS ORIGIN 

SET WM HINTS 

SET WINDOW BACKGROUND 
SET WINDOW BACKGROUND 


PIXMAP 
SET WINDOW BORDER 
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CHANGE GC 


SET FONT PATH 
CHANGE GC 


CHANGE GC 
CHANGE GC 


CHANGE PROPERTY 
CHANGE GC 


CHANGE PROPERTY 
CHANGE GC 


SET SELECTION OWNER 
CHANGE PROPERTY 


CHANGE PROPERTY 


CHANGE GC 


CHANGE GC 
CHANGE GC 
CHANGE GC 
CHANGE GC 
CHANGE PROPERTY 
CHANGE WINDOW 


ATTRIBUTES 


CHANGE WINDOW 
ATTRIBUTES 


CHANGE WINDOW 
ATTRIBUTES 


Description 


Sets the current font of the specified 
graphics context 


Sets the font search path 


Sets the foreground of the specified 
graphics context 


Sets the display function in the 
specified graphics context 


Sets the graphics exposures flag of the 
specified graphics context 


Sets the value of the icon size atom 


Seis the line drawing components of 
the specified graphics context 


Sets the size hints for a window in its 
normal state 


Sets the plane mask of the specified 
graphics context 


Sets the selection owner 


Sets the value of any property of type 
WM_SIZE_HINTS 


Specifies a minimum set of properties 
describing a simple application 


Sets the foreground, background, 
plane mask, and function components 
for the specified graphics context 


Sets the stipple of the specified 
graphics context 


Sets the subwindow mode of the 
specified graphics context 


Sets the fill tile of the specified 
graphics context 


Sets the tile or stipple origin of the 
specified graphics context 


Sets the value of the window manager 
hints atom 


Sets the background of a specified 
window to the specified pixel 


Sets the background of a specified 
window to the specified pixmap 


Changes and repaints a window’s 
border to the specified pixel 
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Protocol Request 


Description 





SET WINDOW BORDER PIXMAP 


SET WINDOW BORDER WIDTH 


SET WINDOW COLORMAP 


SET ZOOM HINTS 
STORE BUFFER 
STORE BYTES 
STORE COLOR 


STORE COLORS 
STORE NAME 
STORE NAMED COLOR 


SYNC 


TRANSLATE COORDINATES 


UNDEFINE CURSOR 


UNLOAD FONT 


UNMAP SUBWINDOWS 


UNMAP WINDOW 


CHANGE WINDOW 
ATTRIBUTES 


CONFIGURE WINDOW 


CHANGE WINDOW 
ATTRIBUTES 


CHANGE PROPERTY 
CHANGE PROPERTY 
CHANGE PROPERTY 
STORE COLORS 


STORE COLORS 
CHANGE PROPERTY 
STORE NAMED COLOR 


GET INPUT FOCUS 


TRANSLATE COORDINATES 


CHANGE WINDOW 
ATTRIBUTES 

CLOSE FONT 

UNMAP SUBWINDOWS 


UNMAP WINDOW 


Changes and repaints a window's 
border tile 


Changes the border width of a window 


Sets the color map of a specified 
window 


Sets the value of the zoom hints atom 
Stores data in specified cut buffer 
Stores data in cut buffer zero 


Stores an RGB value into a single 
color map cell 


Stores RGB values into color map cells 
Assigns a name to a window 


Sets the color of a pixel to the named 
color 


Flushes the output buffer and then 
waits until all requests have been 
processed 


Performs a coordinate transformation 
from the coordinate space of one 
window to another window 


Removes the association of the cursor 
with the specified window 


Unloads the specified font that was 
loaded by LOAD FONT 


Unmaps all subwindows for a specified 
window 


Unmaps a window 


C VMS DECwindows Named Colors 


Table C—1 lists available VMS DECwindows named colors. The table 
provides the color name and the RGB values associated. with that color. 
For a description of using named colors, see Section 5.3.1. 


Table C-1 VMS DECwindows Named Colors 


Named Color Bee values 
Red Green Blue 

Aquamarine 28672 56064 37632 
MediumAquamarine 12800 52224 39168 
Medium Aquamarine 12800 52224 39168 
Black 0 0 0 
Blue 0 0 65280 
CadetBlue 24320 40704 40704 
Cadet Biue 24320 40704 40704 
CornflowerBlue 16896 16896 28416 
Cornflower Blue 16896 16896 28416 
DarkSlateBlue 27392 8960 36352 
Dark Slate Blue 27392 8960 36352 
LightBlue 48896 55296 55296 
Light Blue 48896 55296 55296 
LightSteelBlue 36608 36608 48128 
Light Steel Blue 36608 36608 48128 
MediumBlue 12800 12800 52224 
Medium Blue 12800 12800 52224 
MediumSlateBlue 32512 0 65280 
Medium Slate Blue 32512 0 65280 
MidnightBlue 12032 12032 20224 
Midnight Blue 12032 12032 20224 
NavyBlue 8960 8960 36352 
Navy Blue 8960 8960 36352 
Navy 8960 8960 36352 
SkyBlue 12800 39168 52224 
Sky Blue 12800 39168 52224 
SlateBlue 0 32512 65280 
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Table C—1 (Cont.) VMS DECwindows Named Colors 


Named Color 


Slate Blue 
SteelBiue 

Steel Blue 

Brown 

SandyBrown 

Coral 

Cyan 

Firebrick 

Gold 

Goldenrod 
MediumGoldenrod 
Medium Goldenrod 
Green 

DarkGreen 

Dark Green 
DarkOliveGreen 
Dark Olive Green 
ForestGreen 

Forest Green 
LimeGreen 

Lime Green 
MediumForestGreen 
Medium Forest Green 
MediumSeaGreen 
Medium Sea Green 
MediumSpringGreen 
Medium Spring Green 
PaleGreen 

Pale Green 
SeaGreen 

Sea Green 
SpringGreen 

Spring Green 
YellowGreen 

Yellow Green 


Red 


8960 
8960 
42240 
62464 
65280 


36352 
52224 
56064 
59904 
59904 


12032 
12032 
20224 
20224 
8960 

8960 

12800 
12800 
27392 
27392 
16896 
16896 
32512 
32512 
36608 
36608 
8960 

8960 


39168 
39168 


RGB Values 

Green Blue 
32512 65280 
27392 36352 
27392 36352 
10752 10752 
41984 24576 
32512 0 
65280 65280 
8960 8960 
32512 12800 
56064 28672 
59904 44288 
59904 44288 
65280 0 
20224 12032 
20224 12032 
20224 12032 
20224 12032 
36352 8960 
36352 8960 
52224 12800 
52224 12800 
36352 8960 
36352 8960 
28416 16896 
28416 16896 
65280 0 
65280 0 
48128 36608 
48128 36608 
36352 27392 
36352 27392 
65280 32512 
65280 32512 
52224 12800 
52224 12800 
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Named Color 


DarkSlateGray 
Dark Slate Gray 
Dark Slate Grey 
DarkSlateGrey 
DimGray 

Dim Gray 
DimGrey 

Dim Grey 
LightGray 

Light Gray 
LightGrey 

Light Grey 
Khaki 

Magenta 
Maroon 

Orange 

Orchid 
DarkOrchid 
Dark Orchid 
MediumOrchid 
Medium Orchid 
Pink 

Plum 

Red 

IndianRed 
Indian Red 
MediumVioletRed 
Medium Violet Red 
OrangeRed 
Orange Red 
VioletRed 

Violet Red 
Salmon 

Sienna 

Tan 
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Red 


12032 
12032 
12032 
12032 
21504 
21504 
21504 
21504 
43008 
43008 
43008 
43008 
40704 
65280 
36352 
52224 
56064 
39168 
39168 
37632 
37632 
48128 
59904 
65280 
20224 
20224 
56064 
56064 
65280 
65280 
52224 
52224 
28416 
36352 
56064 


RGB Values 

Green Blue 
20224 20224 
20224 20224 
20224 20224 
20224 20224 
21504 21504 
21504 21504 
21504 21504 
21504 21504 
43008 43008 
43008 43008 
43008 43008 
43008 43008 
40704 24320 
0 65280 
8960 27392 
12800 12800 
28672 56064 
12800 52224 
12800 52224 
28672 56064 
28672 56064 
36608 36608 
44288 59904 
0 0 
12032 12032 
12032 12032 
28672 37632 
28672 37632 
0 32512 
0 32512 
12800 39168 
12800 39168 
16896 16896 
27392 8960 
37632 28672 
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Named Color Bee vellc 
Red Green Blue 

Thistle 55296 48896 §5296 
Turquoise 44288 59904 59904 
DarkTurquoise 28672 37632 56064 
Dark Turquoise 28672 37632 56064 
MediumTurquoise 28672 56064 56064 
Medium Turquoise 28672 56064 56064 
Violet 20224 12032 20224 
BlueViolet 40704 24320 40704 
Blue Violet 40704 24320 40704 
Wheat 55296 55296 48896 
White 65535 65535 65535 
Yellow 65280 65280 0 
GreenYellow 37632 56064 28672 
Green Yellow 37632 56064 28672 





VMS DECwindows Fonis 


Table D-1 lists VMS DECwindows 75 DPI fonts and their file names. 
Table D-2 lists VMS DECwindows 100 DPI fonts and their file names. For 
information about using fonts, see Chapter 8. 


Table D-1 VMS DECwindows 75 DPI Fonts 














File Name Font Name 

FIXED FIXED (MIT) (now ISOLATIN1) 

CURSOR CURSOR (MIT) 

DECW$CURSOR DECW$CURSOR (VMS) 

DECW$SESSION DECWS$SESSION (VMS) 

VARIABLE VARIABLE (MIT) 

AVANT GARDE 

AVANTGARDE_BOOK8 -Adobe-ITC Avant Garde Gothic-Book-R-Normal-8-80-75-75-P-49-ISO8859-1 
AVANTGARDE_BOOK10 -Adobe-ITC Avant Garde Gothic-Book-R-Normal--10-100-75-75-P-59-ISO8859-1 
AVANTGARDE_BOOK12 -Adobe-ITC Avant Garde Gothic-Book-R-Normal—1 2-120-75-75-P-70-ISO8859-1 
AVANTGARDE_BOOK14 -Adobe-ITC Avant Garde Gothic-Book-R-Normal—1 4-140-75-75-P-80-ISO8859-1 
AVANTGARDE_BOOK18 -Adobe-ITC Avant Garde Gothic-Book-R-Normal-18-180-75-75-P-103-ISO8859-1 
AVANTGARDE_BOOK24 -Adobe-ITC Avant Garde Gothic-Book-R-Normal-24-240-75-75-P-138-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE8 -Adobe-ITC Avant Garde Gothic-Book-O-Normal-8-80-75-75-P-49-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE10 -Adobe-ITC Avant Garde Gothic-Book-O-Normal-10-100-75-75-P-59-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE12 -Adobe-ITC Avant Garde Gothic-Book-O-Normal-12-120-75-75-P-69-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE14 -Adobe-ITC Avant Garde Gothic-Book-O-Normal-1 4-140-75-75-P-81-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE18 -Adobe-ITC Avant Garde Gothic-Book-O-Normal-18-180-75-75-P-103-ISO8859-1 
AVANTGARDE_BOOKOBLIQUE24 -Adobe-ITC Avant Garde Gothic-Book-O-Normal-24-240-75-75-P-138-ISO8859-1 
AVANTGARDE_DEMI8 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal-8-80-75-75-P-51-ISO8859-1 
AVANTGARDE_DEMI10 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal-10-100-75-75-P-61-ISO8859-1 
AVANTGARDE_DEMI12 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal-1 2-120-75-75-P-70-ISO8859-1 
AVANTGARDE_DEMI14 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal~14-140-75-75-P-82-ISO8859-1 
AVANTGARDE_DEMI18 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal-18-180-75-75-P-105-ISO8859-1 
AVANTGARDE, DEMI24 -Adobe-ITC Avant Garde Gothic-Demi-R-Normal-24-240-75-75-P-140-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE8 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal-8-80-75-75-P-51 -ISO8859-1 
AVANTGARDE_DEMIOBLIQUE10 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal-10-100-75-75-P-61-ISO8859-1 
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File Name Font Name 

AVANT GARDE 

AVANTGARDE_DEMIOBLIQUE12 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal—12-120-75-75-P-71-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE14 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal—1 4-140-75-75-P-82-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE18 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal-18-180-75-75-P-103-ISO8859-1 
AVANTGARDE_DEMIOBLIQUE24 -Adobe-ITC Avant Garde Gothic-Demi-O-Normal-24-240-75-75-P-139-ISO8859-1 
COURIER 

COURIER10 -Adobe-Courier-Medium-R-Normal-10-100-75-75-M-60-ISO8859-1 

COURIER12 -Adobe-Courier-Medium-R-Normal—1 2-1 20-75-75-M-70-ISO8859-1 

COURIER14 -Adobe-Courier-Medium-R-Normal—1 4-1 40-75-75-M-90-ISO8859-1 

COURIER18 -Adobe-Courier-Medium-R-Normal-18-180-75-75-M-110-ISO8859-1 
COURIER24 -Adobe-Courier-Medium-R-Normal-24-240-75-75-M-150-ISO8859-1 

COURIERS -Adobe-Courier-Medium-R-Normal-8-80-75-75-M-50-ISO8859-1 
COURIER_BOLD10 -Adobe-Courier-Bold-R-Normal—10-100-75-75-M-60-ISO8859-1 
COURIER_BOLD12 -Adobe-Courier-Bold-R-Normal-12-120-75-75-M-70-ISO8859-1 
COURIER_BOLD14 -Adobe-Couner-Bold-R-Normal-1 4-140-75-75-M-90-ISO8859-1 
COURIER_BOLD18 -Adobe-Courier-Bold-R-Normal-18-180-75-75-M-110-ISO8859-1 
COURIER_BOLD24 -Adobe-Courier-Bold-R-Normal-24-240-75-75-M-150-ISO8859-1 
COURIER_BOLD8 -Adobe-Couner-Bold-R-Normat-8-80-75-75-M-50-ISO8859-1 
COURIER_BOLDOBLIQUE10 -Adobe-Courter-Bold-O-Normal~10-100-75-75-M-60-ISO8859-1 
COURIER_BOLDOBLIQUE12 -Adobe-Couner-Bold-O-Normal-12-120-75-75-M-70-ISO8859-1 
COURIER_BOLDOBLIQUE14 -Adobe-Courier-Bold-O-Normal-1 4-140-75-75-M-90-ISO8859-1 
COURIER_BOLDOBLIQUE18 -Adobe-Courier-Bold-O-Normal-18-180-75-75-M-110-ISO8859-1 
COURIER_BOLDOBLIQUE24 -Adobe-Courier-Bold-O-Normal-24-240-75-75-M-150-ISO8859-1 
COURIER_BOLDOBLIQUES -Adobe-Courier-Bold-O-Normal-8-80-75-75-M-50-ISO8859-1 
COURIER_OBLIQUE10 -Adobe-Courier-Medium-O-Normal-10-100-75-75-M-60-ISO8859-1 
COURIER_OBLIQUE12 -Adobe-Courier-Medium-O-Normal-12-120-75-75-M-70-ISO8859-1 
COURIER_OBLIQUE14 -Adobe-Courrer-Medium-O-Normal-14-140-75-75-M-90-ISO8859- 1 
COURIER_OBLIQUE18 -Adobe-Courier-Medium-O-Normal-t 8-1 80-75-75-M-110-ISO8859-1 
COURIER_OBLIQUE24 -Adobe-Courier-Medium-O-Normal—24-240-75-75-M-150-ISO8859-1 
COURIER_OBLIQUE8 -Adobe-Courier-Medium-O-Normal-8-80-75-75-M-50-ISO8859-1 
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File Name Font Name 

HELVETICA 

HELVETICA10 -ADOBE-Helvetica-Medium-R-Normal~10-100-75-75-P-56-ISO8859-1 
HELVETICA12 -ADOBE-Helvetica-Medium-R-Normal—1 2-120-75-75-P-67-ISO8859-1 
HELVETICA14 -ADOBE-Helvetica-Medium-R-Normal—1 4-140-75-75-P-77-ISO8859-1 
HELVETICA18 -ADOBE-Helvetica-Medium-R-Normal—18-180-75-75-P-98-ISO8859-1 
HELVETICA24 -ADOBE-Helvetica-Medium-R-Normal—24-240-75-75-P-130-ISO8859-1 
HELVETICA8 -ADOBE-Helvetica-Medium-R-Normal-8-80-75-75-P-46-ISO8859-1 
HELVETICA_BOLD10 -ADOBE-Helvetica-Bold-R-Normal-10-100-75-75-P-60-ISO8859-1 
HELVETICA_BOLD12 -ADOBE-Helvetica-Bold-R-Normal—12-120-75-75-P-70-ISO8859-1 
HELVETICA_BOLD14 -ADOBE-Helvetica-Bold-R-Normal~14-140-75-75-P-82-ISO8859-1 
HELVETICA_BOLD18 -ADOBE-Helvetica-Bold-R-Normal-18-180-75-75-P-103-ISO8859-1 
HELVETICA_BOLD24 -ADOBE-Helvetica-Bold-R-Normal~-24-240-75-75-P-1 38-ISO8859-1 
HELVETICA_BOLD8 -ADOBE-Helvetica-Bold-R-Normal-8-80-75-75-P-50-ISO8859-1 
HELVETICA_BOLDOBLIQUE10 -ADOBE-Helvetica-Bold-O-Normal—10-100-75-75-P-60-ISO8859-1 
HELVETICA_BOLDOBLIQUE 12 -ADOBE-Helvetica-Bold-O-Normal—1 2-120-75-75-P-69-ISO8859-1 
HELVETICA_BOLDOBLIQUE14 -ADOBE-Helvetica-Bold-O-Normal—1 4-140-75-75-P-82-ISO8859-1 
HELVETICA_BOLDOBLIQUE18 -ADOBE-Helvetica-Bold-O-Normal-1 8-180-75-75-P-104-ISO8859-1 
HELVETICA_BOLDOBLIQUE24 -ADOBE-Helvetica-Bold-O-Normal-24-240-75-75-P-138-iSO8859-1 
HELVETICA_BOLDOBLIQUE8 -ADOBE-Helvetica-Bold-O-Normal-8-80-75-75-P-50-ISO8859-1 
HELVETICA_OBLIQUE10 -ADOBE-Helvetica-Medium-O-Normal-10-100-75-75-P-57-ISO8859-1 
HELVETICA_OBLIQUE12 -ADOBE-Helvetica-Medium-O-Normal—1 2-1 20-75-75-P-67-ISO8859-1 
HELVETICA_OBLIQUE14 -ADOBE-Helvetica-Medium-O-Normal—1 4-1 40-75-75-P-78-ISO8859-1 
HELVETICA_OBLIQUE18 -ADOBE-Helvetica-Medium-O-Normal—1 8-1 80-75-75-P-98-ISO8859-1 
HELVETICA_OBLIQUE24 -ADOBE-Helvetica-Medium-O-Normal-24-240-75-75-P-130-ISO8859-1 
HELVETICA_OBLIQUE8 -ADOBE-Helvetica-Medium-O-Norma!-8-80-75-75-P-47-ISO8859-1 
INTERIM 

INTERIM_DM_EXTENSION14 -ADOBE-Interim DM-Medium-!-Normal—14-1 40-75-75-P-140-DEC-DECMATH_EXTENSION 
INTERIM_DM_ITALIC14 -ADOBE-Interim DM-Medium-l-Normal—14-1 40-75-75-P-140-DEC-DECMATH_ITALIC 
INTERIM_DM_SYMBOL14 -ADOBE-Interim DM-Medium-I-Normal-14-140-75-75-P-140-DEC-DECMATH_SYMBOL 
LUBALIN GRAPH 

LUBALINGRAPH_BOOK8 -Adobe-ITC Lubalin Graph-Book-R-Normal~8-80-75-75-P-50-ISO8859- 1 
LUBALINGRAPH_BOOK10 -Adobe-ITC Lubalin Graph-Book-R-Normal-10-100-75-75-P-60-ISO8859-1 
LUBALINGRAPH_BOOK12 -Adobe-ITC Lubalin Graph-Book-R-Normal-12-120-75-75-P-70-ISO8859-1 
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File Name 


Font Name 





LUBALIN GRAPH 





LUBALINGRAPH_BOOK14. 
LUBALINGRAPH_BOOK18 
LUBALINGRAPH_BOOK24 
LUBALINGRAPH_BOOKOBLIQUE8 
LUBALINGRAPH_BOOKOBLIQUE10 
LUBALINGRAPH_BOOKOBLIQUE12 
LUBALINGRAPH_BOOKOBLIQUE14 
LUBALINGRAPH_BOOKOBLIQUE18 
LUBALINGRAPH_BOOKOBLIQUE24 
LUBALINGRAPH_DEMI8 
LUBALINGRAPH_DEMI10 
LUBALINGRAPH_DEMI12 
LUBALINGRAPH_DEMI14 
LUBALINGRAPH_DEMI18 
LUBALINGRAPH_DEMI24 
LUBALINGRAPH_DEMIOBLIQUE8 
LUBALINGRAPH_DEMIOBLIQUE10 
LUBALINGRAPH_DEMIOBLIQUE12 
LUBALINGRAPH_DEMIOBLIQUE14 
LUBALINGRAPH_DEMIOBLIQUE18 


LUBALINGRAPH_DEMIOBLIQUE24 


-Adobe-ITC Lubalin Graph-Book-R-Normal—1 4-140-75-75-P-81-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-R-Normai—18-180-75-75-P-106-!SO8859-1 
-Adobe-ITC Lubalin Graph-Book-R-Normal-24-240-75-75-P-139-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-O-Normal-8-80-75-75-P-50-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-O-Normal-10-100-75-75-P-60-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-O-Normal-12-120-75-75-P-70-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-O-Normal-14-140-75-75-P-82-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-O-Normal-18-180-75-75-P-105-ISO8859-1 
-Adobe-ITC Lubalin Graph-Book-O-Normal-24-240-75-75-P-1 40-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal-8-80-75-75-P-51-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal-10-100-75-75-P-61-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal—12-120-75-75-P-73-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal-1 4-1 40-75-75-P-85-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal-18-180-75-75-P-109-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-R-Normal-24-240-75-75-P-144-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-O-Normal-8-80-75-75-P-52-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-O-Normal-10-100-75-75-P-62-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-O-Normal—12-120-75-75-P-74-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-O-Normal-14-140-75-75-P-85-ISO8859-1 
-Adobe-ITC Lubalin Graph-Demi-O-Normal-18-180-75-75-P-109-ISO8859-1 


-Adobe-ITC Lubalin Graph-Demi-O-Normal-24-240-75-75-P-144-ISO8859-1 











MENU 

MENU10 -Bigelow & Holmes-Menu-Medium-R-Normal—10-100-75-75-P-56-ISO8859-1 
MENU12 -Bigelow & Holmes-Menu-Medium-R-Normal-1 2-120-75-75-P-70-1SO8859-1 
NEW CENTURY SCHOOLBOOK 





NEWCENTURYSCHLBK_BOLD10 
NEWCENTURYSCHLBK_BOLD12 
NEWCENTURYSCHLBK_BOLD14 
NEWCENTURYSCHLBK_BOLD18 
NEWCENTURYSCHLBK_BOLD24 


NEWCENTURYSCHLBK_BOLD8 


NEWCENTURYSCHLBK_BOLDITALIC10 


-Adobe-New Century Schoolbook-Bold-R-Normal—10-100-75-75-P-66-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal—12-120-75-75-P-77-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal—14-140-75-75-P-87-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Norma!—18-180-75-75-P-113-ISO8859-1 
-Adabe-New Century Schoolbook-Bold-R-Nofmal-24-240-75-75-P-149-ISO8859-1 
-Adobe-New Century Schoolbook-Bold-R-Normal-8-80-75-75-P-56-ISO8859-1 


-Adobe-New Century Schoolbook-Bold-I-Normal-10-100-75-75-P-66-ISO8859-1 
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File Name Font Name 

NEW CENTURY SCHOOLBOOK 

NEWCENTURYSCHLBK_BOLDITALIC12 -Adobe-New Century Schoolbook-Bold-I-Normal-12-120-75-75-P-76-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC14 -Adobe-New Century Schoolbook-Bold-I-Normal-14-140-75-75-P-88-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC18 -Adobe-New Century Schoolbook-Bold-I-Normal-18-180-75-75-P-111-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC24 -Adobe-New Century Schoolbook-Bold-I-Normal-24-240-75-75-P-148-ISO8859-1 
NEWCENTURYSCHLBK_BOLDITALIC8 -Adobe-New Century Schoolbook-Bold-I-Normal-8-80-75-75-P-56-ISO8859-1 
NEWCENTURYSCHLBK_ITALIC10 -Adobe-New Century Schoolbook-Medium-I-Normai—10-100-75-75-P-60-ISO8859-1 
NEWCENTURYSCHLBK_ITALIC12 -Adobe-New Century Schoolbook-Medium-I-Normal-12-120-75-75-P-70-ISO8859-1 
NEWCENTURYSCHLBK_ITALIC14 -Adobe-New Century Schoolbook-Medium-I-Normal-1 4-1 40-75-75-P-81-ISO8859-1 
NEWCENTURYSCHLBK_ITALIC18 -Adobe-New Century Schoolbook-Medium-I-Normal—t 8-180-75-75-P-104-ISO8859-1 
NEWCENTURYSCHLBK_ITALIC24 -Adobe-New Century Schoolbook-Medium-I-Normal-24-240-75-75-P-136-ISO8859-1 
NEWCENTURYSCHLBK_ITALIC8 -Adobe-New Century Schoolbook-Medium-l-Normai~8-80-75-75-P-50-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN10 -Adobe-New Century Schoolbook-Medium-R-Normal-10-100-75-75-P-60-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN12 -Adobe-New Century Schoolbook-Medium-R-Normal~12-120-75-75-P-70-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN14 -Adobe-New Century Schooibook-Medium-R-Normal~1 4-1 40-75-75-P-82-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN18 -Adobe-New Century Schoolbook-Medium-R-Normal-18-180-75-75-P-103-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN24 -Adobe-New Century Schoolbook-Medium-R-Normal-24-240-75-75-P-137-ISO8859-1 
NEWCENTURYSCHLBK_ROMAN8 -Adobe-New Century Schoo!book-Medium-R-Normal-8-80-75-75-P-50-ISO8859-1 
SOUVENIR 

SOUVENIR_DEMI10 -Adobe-!TC. Souvenir-Demi-R-Normal-10-100-75-75-P-62-ISO8859-1 
SOUVENIR_DEMI12 -Adobe-ITC Souvenir-Demi-R-Normal-12-120-75-75-P-75-ISO8859-1 
SOUVENIR_DEMI14 -Adobe-ITC Souvenir-Demi-R-Normal—1 4-1 40-75-75-P-90-ISO8859-1 
SOUVENIR_DEMI18 -Adobe-ITC Souvenir-Demi-R-Normal-18-180-75-75-P-112-ISO8859-1 
SOUVENIR_DEMI24 -Adobe-ITC Souvenir-Demi-R-Normal-24-240-75-75-P-1 49-ISO8859-1 
SOUVENIR_DEMI8 -Adobe-ITC Souvenit-Demi-R-Normal-8-80-75-75-P-52-ISO8859-1 
SOUVENIR_DEMHTALIC10 -Adobe-ITC Souvenir-Demi-!-Normal--10-100-75-75-P-67-ISO8859-1 
SOUVENIR_DEMIITALIC12 -Adobe-ITC Souvenir-Demi-I-Normal-12-120-75-75-P-78-ISO8859-1 
SOUVENIR_DEMIITALIC14 -Adobe-ITC Souvenir-Demi-I-Normal-1 4-140-75-75-P-92-ISO8859-1 
SOUVENIR_DEMIITALIC18 -Adobe-ITC Souvenir-Demi-l-Normal-18-180-75-75-P-115-ISO8859-1 
SOUVENIR_DEMIITALIC24 -Adobe-ITC Souvenir-Demi-l-Normal-24-240-75-75-P-154-ISO8859-1 
SOUVENIR_DEMITALIC8 -Adobe-ITC Souvenit-Dem--Normal-8-80-75-75-P-57-ISO8859-1 
SOUVENIR_LIGHT10 -Adobe-ITC Souvenir-Light-R-Normal—10-100-75-75-P-56-ISO8859-1 
SOUVENIR_LIGHT12 -Adobe-ITC Souvenir-Light-R-Normal—12-120-75-75-P-68-ISO8859-1 
SOUVENIR_LIGHT14 -Adobe-ITC Souvenir-Light-R-Normal—1 4-140-75-75-P-79-ISO8859-1 
SOUVENIR_LIGHT18 -Adobe-ITC Souvenit-Light-R-Normal—1 8-180-75-75-P-102-ISO8859-1 
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SOUVENIR 





SOUVENIR_LIGHT24 
SOUVENIR_LIGHTS 
SOUVENIR_LIGHTITALIC10 
SOUVENIR_LIGHTITALIC12 
SOUVENIR_LIGHTITALIC14 
SOUVENIR_LIGHTITALIC18 
SOUVENIR_LIGHTITALIC24 


SOUVENIR_LIGHTITALICS 


-Adobe-ITC Souvenir-Light-R-Normal-24-240-75-75-P-135-ISO8859-1 
-Adobe-ITC Souvenir-Light-R-Normal-8-80-75-75-P-46-ISO8859-1 
-Adobe-ITC Souvenir-Light-l-Normal~10-100-75-75-P-59-ISO8859-1 
-Adobe-ITC Souvenir-Light-I-Normal-i 2-120-75-75-P-69-ISO8859-1 
-Adobe-ITC Souvenir-Light-l-Normal-t 4-140-75-75-P-82-ISO8859-1 
-Adobe-ITC Souvenir-Light-I-Normal—18-180-75-75-P-104-ISO8859-1 
-Adobe-ITC Souvenir-Light-l-Normal-24-240-75-75-P-139-ISO8859-1 


-Adobe-ITC Souvenit-Light-|-Normal-8-80-75-75-P-49-ISO8859-1 














SYMBOL 

SYMBOL10 -Adobe-Symbo!-Medium-R-Normal~1 0-100-75-75-P-61-ADOBE-FONTSPECIFIC 
SYMBOL12 -Adobe-Symbol-Medium-R-Normal~1 2-120-75-75-P-74-ADOBE-FONTSPECIFIC 
SYMBOL14 -ADOBE-Symbol-Medium-R-Normal-1 4-1 40-75-75-P-85-ADOBE-FONTSPECIFIC 
SYMBOL18 -Adobe-Symbol-Medium-R-Normal-1 8-1 80-75-75-P-107-ADOBE-FONTSPECIFIC 
SYMBOL24 -Adobe-Symbol-Medium-R-Normal-24-240-75-75-P-142-ADOBE-FONTSPECIFIC. 
SYMBOL8 -Adobe-Symbol-Medium-R-Normal-8-80-75-75-P-51-ADOBE-FONTSPECIFIC 
TERMINAL 

TERMINAL14 -DEC-Terminal-Medium-R-Normal—14-140-75-75-C-8-ISO8859-1 

TERMINAL18 -Bitstream-Terminal-Medium-R-Normal—18-180-75-75-C-11-ISO8859-1 
TERMINAL28 -DEC-Terminal-Medium-R-Normal—28-280-75-75-C-16-ISO8859-1 

TERMINAL36 -Bitstream-Terminal-Medium-R-Normal—36-360-75-75-C-22-ISO8859-1 


TERMINAL_BOLD14 

TERMINAL_BOLD18 

TERMINAL_BOLD28 

TERMINAL_BOLD36 
TERMINAL_BOLD_DBLWIDE14 

TERMINAL BOLD_DBLWIDE18 
TERMINAL_BOLD_DBLWIDE_DECTECH14 
TERMINAL_BOLD_DBLWIDE_DECTECH18 
TERMINAL_BOLD_DECTECH14 
TERMINAL_BOLD_DECTECH18 
TERMINAL_BOLD_DECTECH28 


TERMINAL_BOLD_DECTECH36 


-DEC-Terminal-Bold-R-Normal-14-140-75-75-C-8-ISO8859-1 
-Bitstream-Terminal-Bold-R-Normal—18-180-75-75-C-11-ISO8859-1 
-DEC-Terminal-Bold-R-Normal-28-280-75-75-C-16-ISO8859-1 
-Bitstream-Terminal-Bold-R-Normal-36-360-75-75-C-22-ISO8859-1 
-DEC-Terminal-Bold-R-Double Wide—14-140-75-75-C-16-ISO8859-1 
-Bitstream-Terminal-Bold-R-Double Wide—18-180-75-75-C-22-ISO8859-1 
-DEC-Terminal-Bold-R-Double Wide—14-140-75-75-C-16-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Double Wide—18-180-75-75-C-22-DEC-DECtech 
-DEC-Terminal-Bold-R-Normal-14-140-75-75-C-8-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Norma!—1 8-1 80-75-75-C-11-DEC-DECtech 
-DEC-Terminal-Bold-R-Normal-28-280-75-75-C-16-DEC-DECtech 


-Bitstream-Terminal-Bold-R-Normal-36-360-75-75-C-22-DEC-DECtech 
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TERMINAL 





TERMINAL_BOLD_NARROW14 
TERMINAL_BOLD_NARROW18 
TERMINAL_BOLD_NARROW28 
TERMINAL_BOLD_NARROW36 
TERMINAL_BOLD_NARROW_DECTECH14 
TERMINAL_BOLD_NARROW_DECTECH18 
TERMINAL_BOLD_NARROW_DECTECH28 
TERMINAL_BOLD_NARROW_DECTECH36 
TERMINAL_BOLD_WIDE14 
TERMINAL_BOLD_WIDE18 
TERMINAL_BOLD_WIDE_DECTECH14 
TERMINAL_BOLD_WIDE_DECTECH18 
TERMINAL _DBLWIDE14 
TERMINAL_DBLWIDE18 
TERMINAL_DBLWIDE_DECTECH14 
TERMINAL_DBLWIDE_DECTECH18 
TERMINAL_DECTECH14 
TERMINAL_DECTECH18 
TERMINAL_DECTECH28 
TERMINAL_DECTECH36 
TERMINAL_NARROW14 
TERMINAL_NARROW18 
TERMINAL_NARROW28 
TERMINAL_NARROW36 
TERMINAL_NARROW_DECTECH14 
TERMINAL_NARROW_DECTECH18 
TERMINAL_NARROW_DECTECH28 
TERMINAL_NARROW_DECTECH36 
TERMINAL_WIDE14 

TERMINAL_WIDE18 
TERMINAL_WIDE_DECTECH14 


TERMINAL_WIDE_DECTECH18 


-DEC-Terminal-Bold-R-Narrow-1 4-140-75-75-C-6-ISO8859-1 
-Bitstream-Terminal-Bold-R-Narrow—1 8-1 80-75-75-C-7-ISO8859-1 
-DEC-Terminal-Bold-R-Narrow-28-280-75-75-C-12-ISO8859-1 
-Bitstream-Terminal-Bold-R-Narrow-36-360-75-75-C-1 4-ISO8859-1 
-DEC-Terminal-Bold-R-Narrow—1 4-1 40-75-75-C-6-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Narrow~1 8-180-75-75-C-7-DEC-DECtech 
-DEC-Terminal-Bold-R-Narrow~28-280-75-75-C-12-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Narrow-36-360-75-75-C-1 4-DEC-DECtech 
-DEC-Terminal-Bold-R-Wide—14-140-75-75-C-12-ISO8859-1 
-Bitstream-Terminal-Bold-R-Narrow~1 8-180-75-75-C-14-ISO8859-1 
-DEC-Terminal-Bold-R-Wide—14-140-75-75-C-12-DEC-DECtech 
-Bitstream-Terminal-Bold-R-Narrow-1 8-180-75-75-C-14-DEC-DECtech 
-DEC-Terminal-Medium-R-Double Wide—14-140-75-75-C-16-ISO8859-1 
-Bitstream-Terminal-Medium-R-Double Wide-18-180-75-75-C-22-ISO8859-1 
-DEC-Terminal-Medium-R-Double Wide—1 4-140-75-75-C-16-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Double Wide-18-180-75-75-C-22-DEC-DECtech 
-DEC-Terminal-Medium-R-Normal~1 4-1 40-75-75-C-8-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Normal-18-180-75-75-C-11-DEC-DECtech 
-DEC-Terminal-Medium-R-Normal—28-280-75-75-C-16-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Normal-36-360-75-75-C-22-DEC-DECtech 
-DEC-Terminal-Medium-R-Narrow—1 4-1 40-75-75-C-6-ISO8859-1 
-Bitstream-Terminal-Medium-R-Narrow—18-180-75-75-C-7-ISO8859-1 
-DEC-Terminal-Medium-R-Narrow—28-280-75-75-C-12-ISO8859-1 
-Bitstream-Terminal-Medium-R-Narrow~-36-360-75-75-C-14-ISO8859-1 
-DEC-Terminal-Medium-R-Narrow—1 4-140-75-75-C-6-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Natrow—1 8-1 80-75-75-C-7-DEC-DECtech 
-DEC-Terminal-Medium-R-Narrow--28-280-75-75-C-12-DEC-DECtech 
-Bitstream-Terminal-Medium-R-Narrow—-36-360-75-75-C-14-DEC-DECtech 
-DEC-Terminal-Medium-R-Wide—1 4-140-75-75-C-12-ISO8859-1 
-Bitstream-Terminal-Medium-R-Wide—18-180-75-75-C-1 4-ISO8859-1 
-DEC-Terminal-Medium-R-Wide-1 4-1 40-75-75-C-12-DEC-DECtech 


-Bitstream-Terminal-Medium-R-Wide—18-180-75-75-C-1 4-DEC-DECtech 
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TIMES_BOLD10 -ADOBE-Times-Bold-R-Normal—10-100-75-75-P-57-ISO8859-1 
TIMES_BOLD12 -ADOBE-Times-Bold-R-Normal~12-120-75-75-P-67-ISO8859-1 
TIMES_BOLD14 -ADOBE-Times-Bold-R-Normal-14-140-75-75-P-77-ISO8859-1 
TIMES_BOLDi8 -ADOBE-Times-Boid-R-Normal—18-180-75-75-P-99-ISO8859-1 
TIMES_BOLD24 -ADOBE-Times-Bold-R-Normal-24-240-75-75-P-132-ISO8859-1 
TIMES_BOLDS -ADOBE-Times-Bold-R-Normal-8-80-75-75-P-47-ISO8859-1 
TIMES_BOLDITALIC10 -ADOBE-Times-Bold-I-Normal—10-100-75-75-P-57-ISO8859-1 
TIMES_BOLDITALIC12 -ADOBE-Times-Bold-Il-Normal—12-120-75-75-P-68-ISO8859-1 
TIMES_BOLDITALIC14 -ADOBE-Times-Bold-I-Normal—1 4-140-75-75-P-77-ISQ8859-1 
TIMES_BOLDITALIC18 -ADOBE-Times-Bold-I-Normal—1 8-180-75-75-P-98-ISO8859-1 
TIMES_BOLDITALIC24 -ADOBE-Times-Bold-I-Normal-24-240-75-75-P-128-ISO8859-1 
TIMES_BOLDITALIC8 -ADOBE-Times-Boid-I-Normal-8-80-75-75-P-47-ISO8859-1 
TIMES_ITALIC10 -ADOBE-Times-Medium-!-Normal-10-1 00-75-75-P-52-ISO8859-1 
TIMES_ITALIC12 -ADOBE-Times-Medium-I-Normal—12-1 20-75-75-P-63-ISO8859-1 
TIMES_ITALIC14 -ADOBE-Times-Medium-|-Normal-14-1 40-75-75-P-73-ISO8859-1 
TIMES_ITALIC18 -ADOBE-Times-Medium-|-Normal—18-1 80-75-75-P-94-ISO8859-1 
TIMES_ITALIC24 -ADOBE-Times-Medium-I-Normal-24-240-75-75-P-125-ISO8859-1 
TIMES_ITALIC8 -ADOBE-Times-Medium-I-Normat-8-80-75-75-P-42-ISO8859-1 
TIMES_ROMAN10 -ADOBE-Times-Medium-R-Normal-10-100-75-75-P-54-ISO8859-1 
TIMES_ROMAN12 -ADOBE-Times-Medium-R-Normal—12-120-75-75-P-64-1SO8859-1 
TIMES_ROMAN14 -ADOBE-Times-Medium-R-Normal~14-140-75-75-P-74-ISO8859-1 
TIMES_ROMAN18 -ADOBE-Times-Medium-R-Normai-18-180-75-75-P-94-ISO8859-1 
TIMES_ROMAN24 -ADOBE-Times-Medium-R-Normal-24-240-75-75-P-124-ISO8859-1 
TIMES_ROMAN8 -ADOBE-Times-Medium-R-Normal-8-80-75-75-P-44-ISO8859-1 
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AVANT GARDE 





AVANTGARDE_BOOK8_100DPI 
AVANTGARDE_BOOK10_100DPI 
AVANTGARDE_BOOK12_100DPI 
AVANTGARDE_BOOK14_100DPI 
AVANTGARDE_BOOK18_100DPI 
AVANTGARDE_BOOK24_100DPI 
AVANTGARDE_BOOKOBLIQUES8_100DPI 
AVANTGARDE_BOOKOBLIQUE10_100DPI 
AVANTGARDE_BOOKOBLIQUE12_100DPI 
AVANTGARDE_BOOKOBLIQUE14_100DPI 
AVANTGARDE_BOOKOBLIQUE18_100DPI 
AVANTGARDE_BOOKOBLIQUE24_100DPI 
AVANTGARDE_DEMI8_100DPI 
AVANTGARDE_DEMI10_100DPI 
AVANTGARDE_DEMI12_100DPI 
AVANTGARDE_DEMI14_100DPI 
AVANTGARDE_DEMI18_100DPI 
AVANTGARDE_DEMI24_100DPI 
AVANTGARDE_DEMIOBLIQUE8_100DPI 
AVANTGARDE_DEMIOBLIQUE10_100DPI 
AVANTGARDE_DEMIOBLIQUE12_100DPI 
AVANTGARDE_DEMIOBLIQUE 14_100DPI 
AVANTGARDE_DEMIOBLIQUE18_100DP1 


AVANTGARDE_DEMIOBLIQUE24_100DPI 


~Adobe-ITC Adobe-ITC Avant Garde Gothic-Book-R-Normal—11-80-100-100-P-59-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-R-Normal-14-100-100-100-P-80-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-R-Normal-17-120-100-100-P-93-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-R-Normal-20-140-100-100-P-104-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-R-Normal-25-180-100-100-P-138-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-R-Normal-34-240-100-100-P-183-ISO8859-1 
-Avant Garde Gothic-Book-O-Normal-10-80-100-100-P-59-ISO8859-1 

-Adobe-ITC Avant Garde Gothic-Book-O-Normal-14-100-100-100-P-81-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-O-Normal-17-120-100-100-P-92-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-O-Normal-20-1 40-100-100-P-103-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-O-Normal-25-180-100-100-P-138-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Book-O-Normal-34-240-100-100-P-184-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-R-Normal-11-80-100-100-P-61-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-R-Normal-14-100-100-100-P-82-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-R-Normal-17-120-100-100-P-93-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-R-Normal-20-1 40-100-100-P-105-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-R-Normal~25-180-100-100-P-140-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-R-Normal-34-240-100-100-P-182-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-O-Normal~11-80-100-100-P-61-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-O-Normal-1 4-100-100-100-P-82-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-O-Normal—17-120-100-100-P-93-ISO8859-1 
-Adobe-ITC Avant Garde Gothic-Demi-O-Normal-20-140-100-100-P-103-ISO8859-1 
-Adobe-ITG Avant Garde Gothic-Demi-O-Normal~25-180-100-100-P-139-ISO8859-1 


-Adobe-ITC Avant Garde Gothic-Demi-O-Normai-34-240-100-100-P-183-ISO8859-1 





COURIER 





COURIER8_100DPI 
COURIER10_100DPI 
COURIER12_100DP1 
COURIER14_100DPI 
COURIER18_100DPI 
COURIER24_100DPI 
COURIER_BOLD8_100DPI 
COURIER_BOLD10_i00DPI 


COURIER_BOLD12_100DPI 


-Adobe-Courier-Medium-R-Norma!—11-80-100-100-M-60-ISO8859-1 
-Adobe-Courier-Medium-R-Normal—1 4-100-100-100-M-90-ISO8859-1 
-Adobe-Courier-Medium-R-Norma!-17-120-100-100-M-100-!SO8859-1 
-Adobe-Courier-Medium-R-Normal-20-140-100-100-M-110-ISO8859-1 
-Adobe-Courier-Medium-R-Normal-25-1 80-100-100-M-150-ISO8859-1 
-Adobe-Courier-Medium-R-Normal-34-240-100-100-M-200-ISO8859-1 
-Adobe-Courier-Bold-R-Normal-11-80-100-100-M-60-ISO8859-1 
-Adobe-Courier-Bold-R-Normal—14-100-100-100-M-90-ISO8859-1 


-Adobe-Courier-Bold-R-Normal-17-120-100-100-M-100-ISO8859-1 
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COURIER 

COURIER_BOLD14_100DPI -Adobe-Courier-Bold-R-Normal~20-140-100-100-M-110-ISO8859-1 
COURIER_BOLD18_100DP! -Adobe-Courier-Bold-R-Normal-25-180-100-100-M-150-ISO8859-1 
COURIER_BOLD24_100DPI -Adobe-Courier-Bold-R-Normal-34-240-100-100-M-200-ISO8859-1 


COURIER_BOLDOBLIQUE8_100DPI -Adobe-Courier-Bold-O-Normal—11-80-100-100-M-60-ISO8859-1 


COURIER_BOLDOBLIQUE10_100DPI -Adobe-Courier-Bold-O-Normal—1 4-100-100-100-M-90-ISO8859-1 
COURIER_BOLDOBLIQUE12_100DPI -Adobe-Courier-Bold-O-Normal—17-120-100-100-M-100-ISO8859-1 
COURIER_BOLDOBLIQUE14_100DPI -Adobe-Courier-Bold-O-Normal-20-140-100-100-M-110-ISO8859-1 
COURIER_BOLDOBLIQUE18_100DPI -Adobe-Courier-Bold-O-Normal-25-1 80-100-100-M-150-ISO8859-1 


COURIER_BOLDOBLIQUE24_100DPI -Adobe-Courier-Bold-O-Normal~34-240-100-100-M-200-ISO8859-1 


COURIER_OBLIQUE8_100DPI 

COURIER_OBLIQUE10_100DPI 
COURIER_OBLIQUE12_100DPI 
COURIER_OBLIQUE14_100DPI 
COURIER_OBLIQUE18_100DPI 


COURIER_OBLIQUE24_100DPI 


-Adobe-Courier-Medium-O-Normal~11-80-100-100-M-60-ISO8859-1 
-Adobe-Courier-Medium-O-Normal—14-100-100-100-M-90-ISO8859- 1 
-Adobe-Courier-Medium-O-Normal-17-120-100-100-M-100-ISO8859-1 
-Adobe-Courier-Medium-O-Normal-20-140-100-100-M-110-ISO8859-1 
-Adobe-Courier-Medium-O-Normal—25-180-100-100-M-150-ISO8859-1 


-Adobe-Courier-Medium-O-Normal-34-240-100-100-M-200-ISO8859-1 





HELVETICA 





HELVETICA10_100DPI 
HELVETICA12_100DP1 
HELVETICA14_100DPI 
HELVETICA18_100DPI 
HELVETICA24_100DPI 
HELVETICA8_100DPI 
HELVETICA_BOLD10_100DPI 
HELVETICA_BOLD12_100DP! 
HELVETICA_BOLD14_100DP! 
HELVETICA_BOLD18_100DP! 
HELVETICA_BOLD24_100DPI 


HELVETICA_BOLD8_100DPI 


-Adobe-Helvetica-Medium-R-Normal-1 4-100-100-100-P-76-ISO8859-1 
-Adobe-Helvetica-Medium-R-Normal-17-120-100-100-P-88-ISO8859-1 
-Adobe-Helvetica-Medium-R-Normal-20-1 40-100-100-P-100-ISO8859-1 
-Adobe-Helvetica-Medium-R-Normal-25-180-100-100-P-130-ISO8859-1 
-Adobe-Helvetica-Medium-R-Normal-34-240-100-100-P-176-ISO8859-1 
-Adobe-Helvetica-Medium-R-Normal—11-80-100-100-P-56-ISO8859-1 
-Adobe-Helvetica-Bold- R-Normal-1 4-100-100-100-P-82-1SO8859-1 
-Adobe-Helvetica-Bold-R-Normal-1 7-120-100-100-P-92-ISO8859-1 
-Adobe-Helvetica-Bold-R-Normal-20-140-100-100-P-105-iSO8859-1 
-Adobe-Helvetica-Bold-R-Normal-25-180-100-100-P-138-ISO8859-1 
-Adobe-Helvetica-Bold-R-Normai-34-240-100-100-P-182-ISO8859-1 


-Adobe-Helvetica-Bold-R-Normal—t 1-80-100-100-P-60-ISO8859-1 


HELVETICA_BOLDOBLIQUE10_100DPI -Adobe-Helvetica-Bold-O-Normat—1 4-100-100-100-P-82-ISO8859-1 


HELVETICA_BOLDOBLIQUE12_100DPI -Adobe-Helvetica-Bold-O-Normal-17-120-100-100-P-92-ISO8859-1 
HELVETICA_BOLDOBLIQUE14_100DPI -Adobe-Helvetica-Bold-O-Normai-20-1 40-100-100-P-103-ISO8859-1 
HELVETICA_BOLDOBLIQUE18_100DPI -Adobe-Helvetica-Bold-O-Normai~25-1 80-100-100-P-138-ISO8859-1 
HELVETICA_BOLDOBLIQUE24_100DPI -Adobe-Helvetica-Bold-O-Normal-34-240-100-100-P-182-ISO8859-1 


HELVETICA_BOLDOBLIQUE8_100DPI -Adobe-Helvetica-Bold-O-Normal—11-80-100-100-P-60-ISO8859-1 
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HELVETICA_OBLIQUE10_100DPI 
HELVETICA_OBLIQUE12_100DPI 
HELVETICA_OBLIQUE14_100DPI 
HELVETICA_OBLIQUE18_100DPI 
HELVETICA_OBLIQUE24_100DPI 


HELVETICA_OBLIQUE8_100DPI 


-Adobe-Helvetica-Medium-O-Normal-14-100-100-100-P-78-ISO8859- 1 
-Adobe-Helvetica-Medium-O-Normal~17-120-100-100-P-88-ISO8859-1 
-Adobe-Helvetica-Medium-O-Normal~-20-140-100-100-P-98-ISO8859-1 
-Adobe-Helvetica-Medium-O-Normal-25-180-100-100-P-130-ISO8859-1 
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Attribute 
changing window+ 3-38 to 3-40 
defining window + 3-7 
getting information about window* 3-41 to 3-43 


Background color 

specifying + 4-5 
Backing pixel 

definition » 3-11 

effect of changing» 3-40 
Backing plane 

definitions 3-11 

effect of changing» 3-40 
Backing store 

definition» 3-11 

effect of changing* 3-40 
BDF (Bitmap Distribution Format) + A-1 





Bit gravity 

definition * 3-11 

effect of changing » 3-40 
Bitmap 

creating data file for» 7-3 
Bitmap Distribution Format 

See BDF 
Blocking 

definition > 9-56 
Bounding box 

line * 4-11 

text character + 8-1 
Button 

handling presses and releases* 9-8 to 9-11 
Button event data structure * 9-9 


C 


CHANGE WINDOW ATTRIBUTES routine» 3-39 
Char 2B data structure + 8-6 
Char struct data structure» 8-3 
CHECK IF EVENT routine + 9-58 
CHECK MASK EVENT routine » 9-59 
CHECK TYPED EVENT routine» 9-59 
CHECK TYPED WINDOW EVENT routine» 9-59 
CHECK WINDOW EVENT routine * 9-58 
Child window 
See also Window hierarchy 
definition > 1-3 
getting information about» 3-40 
Circulate event data structure » 9-37 
CIRCULATE SUBWINDOWS DOWN routine+ 3-38 
CIRCULATE SUBWINDOWS UP routine» 3-38 
Class hint data structure + 3-27 
CLEAR AREA routine «+ 6-23 
CLEAR WINDOW routine» 6-23 
Client 
communication withs 9-50 to 9-56 
connecting with server* 2-3 
definition» 1-1 
sending message to+ 9-50 
Client message event data structure» 9-51 
Client request 
controlling + 2-8 
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Index 


Client request 
handling by Xlib 
See Server 
Client-server connection 
breaking» 2-4 
establishing » 2-3 
getting information about + 2-5 
Clipping 
specifying pixmap for* 4~10 
CLOSE DISPLAY routine» 2-4 
Color 
allocating for exclusive use» 5-12 
direct» 5-4 
exclusive use of* 5-11 to 5-21 
freeing storage assigned for» 5-21 
gray scales 5-4 
index + 5-2 
named 
list of > C-1 
pseudocolors 5-4 
range of» 5-2 
RGB components + 5-2 
RGB values * 5-4 
screen configuration and+ 5-4 
sharing 5-6 to 5-11 
named* 5-7 to 5-8 
specifying exact value» 5-8 to 5-11 
static gray» 5-4 
type of 
See Visual type 
using named*+ 5-7 
VAXstations that support» 5-6 
Color cell 
allocating for exclusive use* 5-12 to 5-21 
definition » 5-2 
Color data structure * 5-8 
Color index 
definition + 5-2 
Color map» 5-1 to 54 
creating* 5-11 
creating from default» 5-20 
default 
allocating for exclusive use + 5—11 
definition » 5-2 
hardware + 5-4 
receiving notification of change in» 9-49 
specifying» 5-11 to 5-12 
specifying for a window» 3-12 
storing colors» 5-21 
virtual + 5-4 
Color map event data structure » 9-49 
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Color values 
specifying exact+ 5-8 
Configure event data structure + 9-38 
Configure request 
overriding * 3-12 
CONFIGURE WINDOW routine + 3-31 
CONVERT SELECTION routine » 3-30 
COPY AREA routine» 6-24 
COPY COLORMAP AND FREE routine» 5-20 
COPY PLANE routine + 6-24 
CREATE COLORMAP routine» 5-11 
CREATE FONT CURSOR routine « 6-33 
CREATE GLYPH CURSOR routine> 6-33 
CREATE IMAGE routine» 7-7 
CREATE PIXMAP CURSOR routine * 6-37 
CREATE PIXMAP routine * 7~1 
CREATE REGION routine + 6-24 
CREATE SIMPLE WINDOW routine + 3-6 
Create window event data structure » 9-40 
CREATE WINDOW routine + 3-7 
Crossing event data structure» 9-16 
Cursor 
creating 6-32 to 6-38 
using a client cursor font» 6-34 
using pixmaps * 6-37 
using VMS DECwindows cursor font» 6-33 
using Xlib cursor font+ 6-32 
definition + 6-32 
destroying» 6~39 
determining size of» 6-37 
effect of changing default» 3-40 
elements of » 6-34 
illustration of shape and mask» 6-35 
making visible on screens 6-33 
mask + 6—35 
shape+ 6-35 
specifying for a windows 3—12 


D 


Debugging programs* 1-9 
DEFAULT COLORMAP routine + 5-11 
DEFAULT VISUAL OF SCREEN routine» 5-6 
Default window characteristics 
See Window 
DEFINE CURSOR routine+ 6-33 
Depth 
definition » 5-2 
DESTROY SUBWINDOWS routine+ 3-16 





Destroy window event data structure» 9-41 
DESTROY WINDOWS routine + 3—16 
Direct color» 5—4 
Display 
closing» 2-4 
compared to hardware* 2~1 
information routines* 2-5 to 2-8 
openings 2-3 to 2-4 
server response to closings 2-4 to 2-5 
Display information routines* 2-5 to 2-8 
DISPLAY NAME routine » 9-62 
DRAW ARC routine» 6-13 
DRAW ARCS routine» 6-16 
DRAW IMAGE STRING 16 routine» 8-22 
DRAW IMAGE STRING routine + 8-22 
DRAW LINE routine + 6-5 
DRAW LINES routine + 6-6 
DRAW POINT routine» 6-2 
DRAW RECTANGLE routine» 6~9 
DRAW SEGMENTS routine> 6-9 
DRAW STRING 16 routine + 8-21 
DRAW STRING routine+ 8-24 
DRAW TEXT 16 routine» 8-19 
DRAW TEXT routine» 8-19 


E 


Error 
codes* 9-61 
handling event» 9-59 
using default» 9-60 
Error event data structure » 9-60 
Error handling conditions » 1-9 
Error reporting 
delays caused by Xlib buffering» 1-9 
Event 
blocking + 9-56 
button press and release* 9-8 to 9-11 
client communication » 9-50 to 9-56 
client message « 9-50 
color map + 9-49 
convert selection» 9-54 
data structure used to report all types of > 9-3 
data structure used to report multiple types of « 
9-4 
default error handlers « 9-59 
definition » 9-1 
error codes * 9-64 
error handling» 9-59 to 9-62 





Index 


Event (cont’d.) 
graphics exposure * 9-30 to 9-35 
handling queue * 9-56 to 9-59 
key» 9-14 
keyboard mapping» 9-44 
key mappings 9-44 
masks used to specify» 9-5 
notifying ancestors of» 3~12 
pointer * 9-8 
pointer grab* 9-22 
pointer mapping» 9-44 
pointer motions 9~—11 
predicate procedure 
definition» 9-57 
processing 9-1 to 9-4 
property change * 9-51 
reported as result of window eniry or exit» 9-18 
selecting 
using a mask+ 9-58 to 9-59 
using predicate procedure + 9-57 
using the SELECT INPUT routine» 9-5 
when changing window attributes » 9-7 
when creating a window * 9-7 
selecting types of 9-5 to 9-8 
selection notification » 9-55 
selection ownership * 9-53 
sending to other applications » 9-59 
specifying type associated with a window + 3-12 
types* 9-2 
types always reported + 9-5 
window circulation * 9-37 
window creations 9-40 
window destruction * 9-41 
window entry or exit 
caused by a grab* 9-18 
caused by pointer movement* 9~—18 
window exposure * 9-28 to 9-30 
window gravity + 9-42 
window mapping + 9-43 
window reparenting » 9-45 
window unmapping* 9-47 
window visibility» 9-48 
Event data structure * 9-4 
Event mask 
effect of changing » 3-40 
selecting events out of order using» 9-58 
Event queue « 9-56 
checking * 9-57 
putting event back on+ 9-59 
returning next event» 9-57 
EVENTS QUEUED routine « 9-57 
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Expose event data structure» 9-29 
Exposure 
notification of window region» 4—10 


F 


FILL POLYGON routine + 6-20 
Fill style* 4-8 
illustration of * 4-14 
Flags 
for defining color values + 5-9 
for referring to window attributes > 3-13 
for referring to window change values » 3-33 
Focus change event data structure > 9-23 
Font 
advantages of minimum bounding box + A-1 
associating with graphics context» 8-15 
bounding box of» 8-8 
compiling » A—1 
converting from BDF to SNF + A-1 
definition» 8-4 
fixed> 8-4 
getting illustration of when compiling » A—1 
getting information about» 8-15 
getting information about a property » 8-15 
list of VMS DECwindows+ D-1 
loading» 8-14 
monospaced + 8-4 
multiple-row * 8-5 
naming 
conventions when * 8-13 
wildcards used when* 8-14 
pixel size of» 8-14 
point size of + 8-14 
properties * 8-15 
single-row + 8—4 
specifying * 4-10, 8-13 
specifying output files A-1 
Font prop data structure» 8-13 
Font struct data structure» 8-6 
Foreground color 
specifying » 4-4 
FREE COLORMAP routine+ 5-21 
FREE COLORS routine» 5-21 
FREE CURSOR routine + 6-39 
FREE PIXMAP routine» 7-3 
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G 


GC 
See Graphics context 
GC data structure 
default values of» 4—1 
GC values data structure» 4-3 
flags for referring to members of > 4—16 
GET ERROR DATABASE TEXT routine » 9-62 
GET ERROR TEXT routine» 9-62 
GET GEOMETRY routine+ 3—41 
GET IMAGE routine + 7-8 
GET SELECTION OWNER routine * 3-30 
GET WINDOW ATTRIBUTES routine > 3-41 to 
3-43 
Grab 
active + 9-8 
effect on input focus » 9-27 
handling pointer + 9-22 
passive + 9-8 
Graphics 
clearing areas* 6-22 to 6-23 
copying areas * 6-24 
defining characteristics of > 4-2 to 4-21 
defining the position of + 6-1 
drawing 
arcs * 6-13 
lines* 6-5 to 6-9 
points: 6-2 to 6-5 
rectangles + 6~—9 
filling areas» 6-18 to 6-22 
introduction to» 6—1 
position relative to drawable * 6—1 
styles of filling» 4-8 
Graphics characteristics 
See Graphics context 
Graphics context 
changing * 4-22 
copying» 4-22 
default values of» 4—1 
defining in one call* 4-2 
definition > 4-1 
effect of window changes on* 4-22 
maximum number of * 4-23 
overview of* 4—1 
specifying individual components of * 4-18 
using efficiently » 4-22 
Graphics expose event data structure * 9-31 
Graphics exposure * 9-30 to 9-35 
definition » 9-30 


Graphics exposure (cont’d.) 


example of handling + 9-33 
Gravity event data structure - 9-42 
Gray scale* 5-4 


H 


Host machine 
specifying » 2-4 








IF EVENT routine» 9-58 
Image 

changing * 7-10 

creatings 7-7 to 7-8 

from pixmap* 7-8 

creating data file of» 7-3 

destroying» 7-10 

format of * 7-8 

storing» 7-8 

transferring to drawable * 7-8 
image data structure» 7-5 
Inferior window 

definitions 1-3 
Information routines 

as arguments to routines» 2-5 
Input focus 

change caused by grab+ 9-27 

definition» 9-22 

normal keyboard» 9-24 


K 


Key 
mapping events » 9-44 
presses * 9-14 
releases * 9-14 
Keyboard input 
providing window manager hints about + 3-25 
Key event data structure» 9-14 
Key map 
changes in state of + 9-27 
Keymap event data structure » 9-27 
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Line 
dash offset illustrated + 4-16 
double dash* 4-6 
drawing more than one+ 6-6 
endpoints of» 4—6 
how server draws * 4-5 
on off dash* 4-6 
solid» 4-6 
specifying beginning of dashed+ 4—11 
specifying length of dash in dashed+ 4—11 
specifying style of» 4-6 
specifying width of > 4-5 
styles of» 411 
styles of endpoints * 4-12 
styles of filling dashed» 4-8 
styles of joining another + 4-13 
styles of joining another line » 4-7 
treatment of coincident endpoints of > 4-6 
Xlib performance and width of» 4-5 
LIST FONTS routine + 8-15 
LIST FONTS WITH INFO routine + 8-15 
LOAD FONT routine» 8-14 
LOAD QUERY FONT routine» 8-14 
LOOKUP COLOR routine» 5-22 
LOWER WINDOW routine + 3-38 


Map event data structure» 9-43 
Mapping and unmapping windows * 3-16 to 3-17 
Mapping event data structure» 9-44 
MAP RAISED routine» 3-16 
Map request 

overriding» 3-12 
MAP SUBWINDOWS routine + 3-16 
MAP WINDOW routines 3-16 
MASK EVENT routine» 9-58 
Motion event data structure « 9-12 
MOVE RESIZE WINDOW routine» 3-35 
MOVE WINDOW routine + 3-35 
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N 


Named VMS DECwindows colors 
list of > C—1 
using*s 5—7 to 5-8 
NEXT EVENT routine» 9-57 
No expose event data structure » 9-32 


O 


OPEN DISPLAY routine» 2-3 
Origin 

definition» 3-4 
Ownership 

See Window selection 


P 


Parent window 
See also Window hierarchy 
definition » 3-2 
getting information about» 3-40 
receiving notification of change of > 9-45 
using attributes of > 3-6 
PEEK EVENT routine» 9-57 
PEEK IF EVENT routine» 9-58 
PENDING routine» 9-57 
Pixel 
and color values * 5~1 
definition » 3-4 
determining if inside a filled polygon + 4-9 
illustrated * 4-15 
relationship to planes * 5-2 
Pixel value 
computing» 4—4 
Pixmap 
clearing areas of* 6-22 
copying areas of» 6-24 
creating» 7-1 
creating from bitmap data file» 7—4 
example of creating* 7—1 
freeing storage fore 7-3 
Plane 
definition» 5-2 
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Point 


determining location of > 6-3 
drawing more than one» 6~2 
GC members used to draw* 6-3 
Point data structure » 6-2 
Pointer 
button event handling 9-8 to 9-11 
mapping events > 9-44 
motion event handling» 9-11 to 9-14 
Polygon 
filling» 6-19 to 6-22 
GC members used to fill» 6-20 
POLYGON REGION routine» 6-24 
Predicate procedure + 9-58 
Property 
communicating with window manager using » 
3-24 
defining for window manager + 3-24 
defining individual » 3-26 
definition» 3-17 
example of using» 3-21 
exchanging between clients * 3-30 
font+ 8-15 
receiving notification of change in» 9-51 
used by window manager + 3-24 
Property event data structure + 9~52 
Protocol requests * B—1 
Pseudocolor* 5-4 
Pseudomotion 
definition» 9-16 
window eniry or exit» 9-21 
PUT BACK EVENT routine » 9-59 
PUT IMAGE routine» 7-8 


Q 


QUERY BEST CURSOR routine + 6-37 
QUERY BEST SIZE routine+ 4-9 

QUERY COLOR routine+ 5-22 

QUERY POINTER routine» 3-41 

QUERY TEXT EXTENTS 16 routine» 8-17 
QUERY TEXT EXTENTS routine» 8-17 
QUERY TREE routine» 3-41 


R 


RAISE WINDOW routine + 3-38 














Rectangle 


drawing more than one» 6-10 
filling» 6-18 
GC members used to draw* 6-11 
GC members used to fill» 6-19 
Rectangle data structure» 6-11 
Region 
creating* 6-24 to 6-27 
definition + 6-24 
example of intersecting » 6-28 
managing» 6-27 to 6-31 
Reparent event data structure» 9-46 
Request 
buffering» 1-9 
client» 1-9 
how Xlib handles client» 1-9 
RESIZE WINDOW routine + 3-35 
RESTACK WINDOW routine» 3-38 
Root window + 3-2 
definition + 1-3 
Routines 
ALLOC COLOR « 5-8 
ALLOC COLOR CELLS» 5-12 
ALLOC NAMED COLORs 5-7 
CHANGE WINDOW ATTRIBUTES * 3-39 
CHECK IF EVENT 9-58 
CHECK MASK EVENT + 9-59 
CHECK TYPED EVENT» 9-59 
CHECK TYPED WINDOW EVENT + 9-59 
CHECK WINDOW EVENT * 9-58 
CIRCULATE SUBWINDOWS DOWN + 3-38 
CIRCULATE SUBWINDOWS UP + 3-38 
CLEAR AREA* 6-23 
CLEAR WINDOW « 6-23 
CLOSE DISPLAY + 2-4 
CONFIGURE WINDOW + 3-31 
CONVERT SELECTION + 3-30 
COPY AREA» 6-24 
COPY COLORMAP AND FREE « 5-20 
COPY PLANE + 6-24 
CREATE COLORMAP « 5-11 
CREATE FONT CURSOR « 6-33 
CREATE GLYPH CURSOR « 6-33 
CREATE IMAGE + 7-7 
CREATE PIXMAP « 7-1 
CREATE PIXMAP CURSOR * 6-37 
CREATE REGION + 6-24 
CREATE SIMPLE WINDOW « 3-6 
CREATE WINDOW « 3-7 
DEFAULT COLORMAP « 5-11 
DEFAULT VISUAL OF SCREEN + 5-6 
DEFINE CURSOR « 6-33 


Index 


Routines (cont’d.) 


DESTROY SUBWINDOWS + 3-16 
DISPLAY NAME « 9-62 

DRAW ARC « 6-13 

DRAW ARCS « 6-16 

DRAW IMAGE STRING « 8-22 
DRAW IMAGE STRING 16¢ 8-22 
DRAW LINE « 6-5 

DRAW LINES « 6-6 

DRAW POINT + 6-2 

DRAW RECTANGLE + 6-9 
DRAW SEGMENTS + 6-9 
DRAW STRING» 8-21 

DRAW STRING 16¢ 8-21 
DRAW TEXT» 8-19 

DRAW TEXT 16° 8-19 
EVENTS QUEUED* 9-57 

FILL POLYGON « 6~20 

FREE COLORMAP « 5-21 

FREE COLORS» 5-21 

FREE CURSOR 6-39 

FREE PIXMAP « 7-3 

GET ERROR DATABASE TEXT + 9-62 
GET ERROR TEXT = 9-62 

GET GEOMETRY * 3-41 

GET IMAGE « 7-8 

GET SELECTION OWNER * 3-30 
GET WINDOW ATTRIBUTES « 3-41 to 3-43 
IF EVENT + 9-58 

LIST FONTS + 8~15 

LIST FONTS WITH INFO + 8-15 
LOAD FONT+ 8~14 

LOAD QUERY FONT+ 8-14 
LOOKUP COLOR» 5-22 
LOWER WINDOW *« 3-38 

MAP RAISED «+ 3-16 

MAP SUBWINDOWS « 3-16 
MAP WINDOW + 3-16 

MASK EVENT + 9-58 

MOVE RESIZE WINDOW « 3-35 
MOVE WINDOW « 3-35 

NEXT EVENT + 9-57 

OPEN DISPLAY « 2-3 

PEEK EVENT + 9-57 

PEEK IF EVENT + 9-58 
PENDING + 9-87 

POLYGON REGION + 6-24 
PUT BACK EVENT + 9-59 

PUT IMAGE + 7-8 

QUERY BEST CURSOR + 6-37 
QUERY BEST SIZE+ 4-9 
QUERY COLOR «+ 5-22 
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Routines (cont'd.) 


QUERY POINTER ®* 3-41 

QUERY TEXT EXTENTS* 8-17 
QUERY TEXT EXTENTS 16¢ 8-17 
QUERY TREE» 3-41 

RAISE WINDOW + 3-38 

requiring protocol requests * B-1 
RESIZE WINDOW + 3-35 
RESTACK WINDOW « 3-38 
SELECT INPUT + 9-5 

SEND EVENT + 9-59 

SET ERROR ROUTINE + 9-60 
SET FONT+ 8-15 

SET 10 ERROR HANDLER « 9-62 
SET SELECTION OWNER « 3-30 
SET WINDOW BORDER WIDTH + 3-35 
SET WM HINTS « 3-25 

STORE COLOR 5-21 

STORE COLORS « 5-21 

STORE NAMED COLOR» 5-21 
SYNCHRONIZE + 9-59 

TEXT EXTENTS « 8-17 

TEXT EXTENTS 16° 8-17 

TEXT WIDTH 8~17 

TEXT WIDTH 16° 8-17 
UNDEFINE CURSOR « 6-38 
UNMAP SUBWINDOWS + 3-17 
UNMAP WINDOW « 3-17 
WINDOW EVENT « 9-58 


S 


Save under operation 
definition» 3~-12 
effect of changing» 3-40 
Screen 
specifying display + 2-4 
updating pixel values * 4~4 
Screen type 





See Visual type 
Segment data structure» 6-8 
SELECT INPUT routine + 9-5 
Selection 

See Window selection 
Selection clear event data structure » 9-53 
Selection event data structure» 9-55 
Selection request event data structure * 9-54 
SEND EVENT routine» 9-59 
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Server 


client requests to» 1-9 

definition» 1-1 

managing requests * 2~8 

relationship to client» 2-1 
Server access control list 

definitions 2-5 
Server Natural Form 

See SNF 
SET ERROR HANDLER routine » 9-60 
SET FONT routine» 8-15 
SET IO ERROR HANDLER routine» 9-62 
SET SELECTION OWNER routine» 3-30 
Set window attributes data structure * 3-8 
SET WINDOW BORDER WIDTH routine» 3-35 
SET WM HINTS routine » 3-25 
Size hints data structure» 3-28 
SNF (Server Natural Form) * A—1 
Stacking order 

changing* 3-37 to 3-38 
Static gray * 5—4 
Stippling 

origin fore 4—10 

specifying pixmap for» 4—10 
STORE COLOR routine + 5-21 
STORE COLORS routine + 5-21 
STORE NAMED COLOR routine 5-21 
Subwindow 

lowering * 3-38 

mapping» 3-16 

movement when reconfiguring parent+ 3-35 

raising * 3-38 

reordering in hierarchy * 3-16 
SYNCHRONIZE routine » 9-59 
Synchronous operation» 9-59 


T 


Text 
computing size of> 8-17 
drawing + 8-18 
example of drawing with DRAW STRING=« 8-21 
example of drawing with DRAW TEXT + 8-19 
styles of filling + 4-8 
text character 
definition» 8-1 
illustrated 8-1 
positioning » 8-1 
TEXT EXTENTS 16 routine» 8-17 
TEXT EXTENTS routine» 8-17 








Text item 16 data structure» 8-19 
Text item data structure * 8-18 
TEXT WIDTH 16 routine» 8-17 
TEXT WIDTH routine + 8-17 
Tiling 

origin for* 4-10 

specifying pixmap for* 4-9 
Transport mechanism + 2—4 


U 


UNDEFINE CURSOR routine » 6-38 
Unmap event data structure + 9-47 
UNMAP SUBWINDOWS routine * 3-17 
UNMAP WINDOW routine + 3-17 


V 


Visibility event data structure » 9-48 
Visual type 

default» 5-6 

definition» 5—4 

determining + 5-6 

direct colors 5—4 

gray scales 5—4 

pseudocolor+ 5-4 

static gray * 5-4 

using to share colors 5—4 


W 


Window 
associating properties with» 3-17 
changing 
attributes > 3-38 to 3-40 
characteristics of * 3-31 
stacking order* 3-37 to 3-38 
circulation 
receiving notification of > 9-37 
clearing areas of * 6-23 
clearing areas with FILL RECTANGLES * 6-23 
copying areas of + 6-24 
creating 
receiving notification of » 9-40 
using attributes of parent» 3-6 
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Window (cont’d.) 
creating and specifying attributes of» 3-7 to 
3-16 
creating simple* 3-6 to 3-7 
default characteristics * 3-6 
destroying» 3-16 
receiving notification of > 9-41 
entries and exits» 9-15 
example of configuring » 3-33 
example of creating simple * 3-7 
example of mapping and raising in hierarchy « 
3-16 
flags for referring to attributes » 3-13 
getting information about* 3-40 to 3-43 
initial state 
providing window manager hints about* 3-25 
lowering in the hierarchy * 3-38 
mapping» 3-16 
receiving notification of > 9-43 
obscurings 3-5 
treating» 3-11 
overview of* 3-1 
parent 
definition * 3-2 
receiving notification of change of + 9-45 
position relative to parent» 3-4 
raising in the hierarchy * 3-38 
reconfiguration 
effects on graphics and text» 3-35 
resizing» 3-31 
restacking 
constants for specifying » 3-32 
restoring contents of exposed+ 9-28 
saving contents of another * 3-12 
specifying background color of* 4-5 
specifying color maps for* 3~—12 
specifying cursor for* 3-12 
specifying foreground color of > 4-4 
types of * 3-1 
unmapping + 3-16 
receiving notification of» 9-47 
visibility of » 3-5 
receiving notification of change ins 9-48 
Window attribute 
data structure used to define* 3-8 
default value of > 3-12 
defining * 3-7 to 3-16 
Window attributes data structure» 3-41 
Window background 
effect of changing» 3-40 
repainting * 3-40 
server treatment of > 3-10 
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Window background (cont’d.) 
specifying when creating a window* 3-6 to 3-7, 
3-9 to 3-10 
using a pixel to define» 3~10 
using a pixmap to define + 3-9 
Window border 
effect of changing+ 3-40 
effect on graphic operations » 3-11 
specifying when creating a window* 3-6 to 3~7, 
3-11 
using a pixel to define» 3-11 
using a pixmap to define» 3-11 
Window changes data structure * 3-31 
Window clipping 
specifying » 4-10 
Window contents 
managing when window is resized + 3-11 
preserving* 3-14 
repainting when obscured » 3-11 
saving* 3-12 
Window coordinate system+* 3—4 to 3-5 
Window entry or exit 
caused by a grab+ 9-18 
caused by pointer movement+ 9-18 
events reported as result of * 9-18 
example of handling > 9-19 
pseudomotion + 9-21 
Window event 
See Event 
WINDOW EVENT routine + 9-58 
Window exposure * 9-28 to 9-30 
definition » 9-28 
example of handling * 9-30 
Window gravity 
definition» 3-11 
effect of changing» 3-40 
Window hierarchy * 3-2 to 3-4 
Window icon 
providing window manager hints about» 3-25 
Window manager 
providing hints to» 3-24 
working with » 3-24 
Window movement 
managing when parent is resized* 3-11 
Window obscuring « 3-5 
treating* 3-11 
Window occlusion + 3-5 
Window position 
receiving notification of change in» 9-42 
specifying when creating a windows 3-6 to 3-7 
Window restacking + 3-38 
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Window selection 

definition» 3-30 

receiving notification of > 9-53 

receiving notification of request for» 9-55 

receiving request to convert» 9-54 
Window size 

specifying when creating a window+ 3-6 to 3-7 
Window visibility > 3-5 

See also Mapping 

receiving notification of changes in» 9-48 
WM hints data structure » 3-25 


X 


Xlib program 

sample of* 1-2 
XY bitmap format + 7-8 
XY pixmap format+ 7-8 


Z 


Z pixmap format + 7-9 
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If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing 


your electronic, telephone, or direct mail order. 


Electronic Orders 


To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud 
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825). 


Telephone and Direct Mail Orders 


Your Location Call 


Continental USA, 800-DIGITAL 
Alaska, or Hawaii 


Puerto Rico 809-754-7575 
Canada 800-267-6215 
International 

Internal! 


Contact 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, New Hampshire 03061 


Local DIGITAL subsidiary 


Digital Equipment of Canada 

Attn: DECdirect Operations KAO2/2 
P.O. Box 13000 

100 Herzberg Road 

Kanata, Ontario, Canada K2K 2A6 


Local DIGITAL subsidiary or 
approved. distributor 


SDC Order Processing - WMO/E15 
or 

Software Distribution Center 
Digital Equipment Corporation 
Westminster, Massachusetts 01473 


1¥or internal orders, you must submit an Internal Software Order Form (EN-01740-07). 
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